claude-plugins/claude-code/skills/project-mcp-setup/skill.md

Project MCP Setup Templates

When to Use This Skill

Use this skill when you need to quickly create a .mcp.json file for a new project with common MCP server configurations. This skill provides pre-configured templates so you don't have to look up MCP settings every time.

Triggers:

• User mentions creating or setting up .mcp.json for a project
• User wants to configure MCPs for a specific project type (technical, prose, minimal)
• User asks to "set up MCPs" or "configure MCP servers"

Do NOT use for:

• Configuring MCPs in plugins (use claude-code:mcp-config skill)
• Creating MCP servers (use example-skills:mcp-builder skill)

Available Templates

1. Technical Projects

Full-featured setup for software development:

• gitea: Issue and PR management for Gitea-hosted repos
• ya-memory: Persistent memory across conversations
• ya-rag: Document indexing and semantic search
• sequential-thinking: Complex problem-solving
• rubber-duck: Debugging assistant

2. Prose/Writing Projects

Minimal setup focused on writing:

• ya-memory: Character tracking, world-building notes
• rubber-duck: Brainstorming and feedback

3. Minimal Projects

Bare essentials:

• ya-memory: Basic memory only

4. Custom

Let the user specify which MCPs they want from their user configuration.

Template Definitions

Technical Template

{
  "mcpServers": {
    "gitea": {
      "command": "uvx",
      "args": ["mcp-server-gitea"],
      "env": {
        "GITEA_BASE_URL": "${GITEA_BASE_URL:-https://code.movq.us}",
        "GITEA_TOKEN": "${GITEA_TOKEN}"
      }
    },
    "ya-memory": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/russellballestrini/ya-memory-mcp.git", "ya-memory-mcp"],
      "env": {
        "YA_MEMORY_BASE_DIR": "${YA_MEMORY_BASE_DIR:-~/.ya-memory}"
      }
    },
    "ya-rag": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/russellballestrini/ya-rag-mcp.git", "ya-rag-mcp"],
      "env": {
        "YA_RAG_BASE_DIR": "${YA_RAG_BASE_DIR:-~/.ya-rag}"
      }
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "rubber-duck": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/russelballestrini/rubber-duck-mcp.git", "rubber-duck-mcp"]
    }
  }
}

Prose Template

{
  "mcpServers": {
    "ya-memory": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/russellballestrini/ya-memory-mcp.git", "ya-memory-mcp"],
      "env": {
        "YA_MEMORY_BASE_DIR": "${YA_MEMORY_BASE_DIR:-~/.ya-memory}"
      }
    },
    "rubber-duck": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/russelballestrini/rubber-duck-mcp.git", "rubber-duck-mcp"]
    }
  }
}

Minimal Template

{
  "mcpServers": {
    "ya-memory": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/russellballestrini/ya-memory-mcp.git", "ya-memory-mcp"],
      "env": {
        "YA_MEMORY_BASE_DIR": "${YA_MEMORY_BASE_DIR:-~/.ya-memory}"
      }
    }
  }
}

Usage Instructions

When this skill is invoked:

1. Ask the user which template they want (unless they already specified):

   • Technical (software development with full tooling)
   • Prose (writing projects)
   • Minimal (just memory)
   • Custom (user specifies MCPs)

2. For Custom, ask which MCPs they want to include from:

   • gitea
   • ya-memory
   • ya-rag
   • sequential-thinking
   • rubber-duck
   • (or any others they specify)

3. Check if .mcp.json already exists in the current directory:

   • If yes, ask if they want to overwrite or merge
   • If merge, combine configurations

4. Generate the .mcp.json file with the selected template

5. Inform the user:

   • Where the file was created
   • What MCPs were included
   • That they need to restart Claude Code or use /mcp reload to load the new configuration
   • Any required environment variables they need to set

Environment Variables Reference

Document these common environment variables:

• GITEA_BASE_URL: Gitea instance URL (default: https://code.movq.us)
• GITEA_TOKEN: Gitea API token (required for gitea MCP)
• YA_MEMORY_BASE_DIR: Memory storage location (default: ~/.ya-memory)
• YA_RAG_BASE_DIR: RAG index location (default: ~/.ya-rag)

Example Interactions

Example 1: Quick technical setup

User: Set up MCPs for this project
Assistant: I'll help you set up a .mcp.json file. What type of project is this?
- Technical (software development)
- Prose (writing)
- Minimal (just memory)
- Custom

User: Technical
Assistant: [Creates .mcp.json with technical template]

Example 2: Direct request

User: Create a .mcp.json with just memory and rubber duck
Assistant: [Creates .mcp.json with those two MCPs]

Example 3: Merge existing

User: Add gitea to my MCP config
Assistant: I see you already have a .mcp.json with ya-memory. I'll add gitea to it.
[Merges gitea into existing config]

Key Points

• Project-specific: These .mcp.json files are for individual projects, not global
• Restartable: Changes require Claude Code restart or /mcp reload
• Committable: These files can be committed to version control (but not with secrets)
• Environment variables: Use ${VAR} syntax with optional defaults like ${VAR:-default}
• Additive: Can be added to existing projects without affecting user-level MCPs

Related Skills

• claude-code:mcp-config: For plugin MCP configuration
• example-skills:mcp-builder: For creating new MCP servers