# MCP Servers Configuration for ClaudeTools

**Last Updated:** 2026-01-17
**Status:** Configured and Ready for Testing
**Phase:** Phase 1 - Core MCP Servers

---

## Overview

This document describes the Model Context Protocol (MCP) servers configured for the ClaudeTools project. MCP servers extend Claude Code's capabilities by providing specialized tools and integrations.

**What is MCP?**
Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs, allowing AI applications to connect with various data sources and tools in a consistent manner.

**Official Resources:**
- MCP Registry: https://registry.modelcontextprotocol.io/
- Official GitHub: https://github.com/modelcontextprotocol/servers
- Documentation: https://modelcontextprotocol.io/
- Claude Code MCP Docs: https://code.claude.com/docs/en/mcp

---

## Installed MCP Servers

### 1. GitHub MCP Server

**Package:** `@modelcontextprotocol/server-github`
**Purpose:** Repository management, PR operations, and GitHub API integration
**Status:** Configured (requires GitHub Personal Access Token)

**Capabilities:**
- Repository management (create, clone, fork)
- File operations (read, write, push)
- Branch management (create, list, switch)
- Git operations (commit, push, pull)
- Issues handling (create, list, update, close)
- Pull request management (create, review, merge)
- Search functionality (code, issues, repositories)

**Configuration:**
```json
{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN_HERE>"
    }
  }
}
```

**Setup Steps:**

1. **Generate GitHub Personal Access Token:**
   - Go to: https://github.com/settings/tokens
   - Click "Generate new token (classic)"
   - Select scopes: `repo`, `workflow`, `read:org`, `read:user`
   - Copy the generated token

2. **Add Token to Configuration:**
   - Edit `D:\ClaudeTools\.mcp.json`
   - Replace `<YOUR_TOKEN_HERE>` with your actual token
   - **IMPORTANT:** Do NOT commit the token to version control
   - Consider using environment variables or secrets management

3. **Restart Claude Code** to load the new configuration

**Gitea Integration Notes:**
- The official GitHub MCP server is designed for GitHub.com
- For self-hosted Gitea integration, you may need:
  - Custom MCP server or adapter
  - Gitea API endpoint configuration
  - Alternative authentication method
- See "Future Gitea Integration" section below

---

### 2. Filesystem MCP Server

**Package:** `@modelcontextprotocol/server-filesystem`
**Purpose:** Enhanced file system operations with safety controls
**Status:** Configured and Ready

**Capabilities:**
- Read files with proper permissions
- Write files with safety checks
- Directory management (create, list, delete)
- File metadata access (size, modified time, permissions)
- Search files and directories
- Move and copy operations
- Sandboxed directory access

**Configuration:**
```json
{
  "filesystem": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "D:\\ClaudeTools"
    ]
  }
}
```

**Access Control:**
- Currently restricted to: `D:\ClaudeTools`
- Add additional directories by appending paths to `args` array
- Example for multiple directories:
  ```json
  "args": [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "D:\\ClaudeTools",
    "D:\\Projects",
    "C:\\Users\\YourUser\\Documents"
  ]
  ```

**Safety Features:**
- Directory access control (only specified directories)
- Permission validation before operations
- Read-only mode available (mount with `:ro` flag in Docker)
- Prevents accidental system file modifications

**Usage Examples:**
- Read project files with context awareness
- Safe file modifications with backups
- Directory structure analysis
- File search across allowed directories

---

### 3. Sequential Thinking MCP Server

**Package:** `@modelcontextprotocol/server-sequential-thinking`
**Purpose:** Structured problem-solving and step-by-step analysis
**Status:** Configured and Ready

**Capabilities:**
- Step-by-step thinking process
- Problem decomposition
- Logical reasoning chains
- Complex analysis structuring
- Decision tree navigation
- Multi-step task planning

**Configuration:**
```json
{
  "sequential-thinking": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-sequential-thinking"
    ]
  }
}
```

**Optional Configuration:**
- Disable thought logging: Set environment variable `DISABLE_THOUGHT_LOGGING=true`
- Example:
  ```json
  "sequential-thinking": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
    "env": {
      "DISABLE_THOUGHT_LOGGING": "true"
    }
  }
  ```

**Usage Scenarios:**
- Complex debugging sessions
- Architecture design decisions
- Multi-step refactoring plans
- Problem diagnosis
- Performance optimization planning

---

## Installation Details

### Prerequisites

- **Node.js:** v24.11.0 (installed)
- **npm/npx:** Included with Node.js
- **Claude Code:** Latest version with MCP support

### Installation Method

All three MCP servers use **npx** for installation, which:
- Downloads packages on-demand (no manual npm install needed)
- Automatically updates to latest versions
- Runs in isolated environments
- Requires no global installations

### Configuration File Location

**Project-Scoped Configuration:**
- File: `D:\ClaudeTools\.mcp.json`
- Scope: ClaudeTools project only
- Version Control: Can be committed (without secrets)
- Team Sharing: Configuration shared across team

**User-Scoped Configuration:**
- File: `~/.claude.json` (C:\Users\YourUser\.claude.json on Windows)
- Scope: All Claude Code projects for current user
- Not shared: User-specific settings

**Recommendation:** Use project-scoped `.mcp.json` for team consistency, but store sensitive tokens in user-scoped config or environment variables.

---

## Testing MCP Servers

### Test 1: Sequential Thinking Server

**Test Command:**
```bash
npx -y @modelcontextprotocol/server-sequential-thinking --help
```

**Expected:** Server runs without errors

**In Claude Code:**
- Ask: "Use sequential thinking to break down the problem of optimizing database queries"
- Verify: Claude provides step-by-step analysis

---

### Test 2: Filesystem Server

**Test Command:**
```bash
npx -y @modelcontextprotocol/server-filesystem --help
```

**Expected:** Server runs without errors

**In Claude Code:**
- Ask: "List all Python files in the api directory"
- Ask: "Read the contents of api/main.py and summarize"
- Verify: Claude can access files in D:\ClaudeTools

---

### Test 3: GitHub Server

**Test Command:**
```bash
npx -y @modelcontextprotocol/server-github --help
```

**Expected:** Server runs without errors

**In Claude Code (after adding token):**
- Ask: "List my recent GitHub repositories"
- Ask: "Show me open pull requests for ClaudeTools"
- Verify: Claude can access GitHub API

**Note:** Requires valid `GITHUB_PERSONAL_ACCESS_TOKEN` in configuration

---

## Troubleshooting

### Issue: MCP Servers Not Appearing in Claude Code

**Solutions:**
1. Verify `.mcp.json` syntax (valid JSON)
2. Restart Claude Code completely (quit and relaunch)
3. Check Claude Code logs for errors
4. Verify npx works: `npx --version`

---

### Issue: GitHub MCP Server - Authentication Failed

**Solutions:**
1. Verify token is correct in `.mcp.json`
2. Check token scopes include: `repo`, `workflow`, `read:org`
3. Test token manually:
   ```bash
   curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user
   ```
4. Regenerate token if expired

---

### Issue: Filesystem MCP Server - Access Denied

**Solutions:**
1. Verify directory path in configuration matches actual path
2. Check Windows path format: `D:\\ClaudeTools` (double backslashes)
3. Ensure directory exists and is readable
4. Add additional directories to `args` array if needed

---

### Issue: Sequential Thinking Server - No Output

**Solutions:**
1. Explicitly ask Claude to "use sequential thinking"
2. Check if `DISABLE_THOUGHT_LOGGING=true` is set
3. Try with a complex problem that requires multi-step reasoning

---

## Security Considerations

### GitHub Token Security

**DO:**
- Use fine-grained tokens with minimal required scopes
- Store tokens in environment variables or secrets manager
- Rotate tokens regularly (every 90 days)
- Use separate tokens for different environments

**DO NOT:**
- Commit tokens to version control
- Share tokens in team chat or documentation
- Use admin-level tokens for routine operations
- Store tokens in plaintext configuration files (committed to git)

**Best Practice:**
```json
{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}
```
Then set `GITHUB_TOKEN` environment variable in your shell or user config.

---

### Filesystem Access Control

**Current Configuration:**
- Access limited to: `D:\ClaudeTools`
- Prevents accidental system file modifications
- Safe for automated operations

**Adding Directories:**
- Only add directories that Claude Code should access
- Avoid adding system directories (C:\Windows, etc.)
- Consider read-only access for sensitive directories

---

## Future Gitea Integration

### Current Status

The GitHub MCP server (`@modelcontextprotocol/server-github`) is designed for GitHub.com and may not work directly with self-hosted Gitea instances.

### Integration Options

**Option 1: Custom MCP Server for Gitea**
- Create custom MCP server using Gitea API
- Based on MCP Python SDK or TypeScript SDK
- Full control over authentication and features
- Effort: High (development required)

**Option 2: GitHub MCP Server with Adapter**
- Modify GitHub MCP server to support Gitea endpoints
- Fork `@modelcontextprotocol/server-github`
- Update API endpoints to point to Gitea instance
- Effort: Medium (modification required)

**Option 3: Generic Git MCP Server**
- Use git CLI-based MCP server
- Works with any git remote (including Gitea)
- Limited to git operations (no PR/issue management)
- Effort: Low (may already exist)

### Required Gitea Configuration

For any Gitea integration, you'll need:

1. **Gitea Access Token:**
   - Generate from: `https://your-gitea-instance.com/user/settings/applications`
   - Required scopes: `repo`, `user`, `api`

2. **API Endpoint:**
   - Gitea API: `https://your-gitea-instance.com/api/v1`
   - Compatible with GitHub API v3 (mostly)

3. **Environment Variables:**
   ```json
   "env": {
     "GITEA_TOKEN": "your-gitea-token",
     "GITEA_HOST": "https://your-gitea-instance.com",
     "GITEA_API_URL": "https://your-gitea-instance.com/api/v1"
   }
   ```

### Next Steps for Gitea Integration

1. Research existing Gitea MCP servers in registry
2. Evaluate GitHub MCP compatibility with Gitea API
3. Consider developing custom Gitea MCP server
4. Document Gitea-specific configuration
5. Test with Gitea instance

**Recommendation:** Start with Option 3 (Generic Git MCP) for basic operations, then evaluate custom development for full Gitea API integration.

---

## Additional MCP Servers (Future Consideration)

### Potential Phase 2 Servers

1. **Database MCP Server**
   - Direct MariaDB/MySQL integration
   - Query execution and schema inspection
   - Useful for ClaudeTools database operations

2. **Docker MCP Server**
   - Container management
   - Image operations
   - Useful for deployment automation

3. **Slack MCP Server**
   - Team notifications
   - Integration with work tracking
   - Useful for status updates

4. **Browser Automation MCP**
   - Playwright/Puppeteer integration
   - Testing and scraping
   - Useful for web-based testing

---

## References and Resources

### Official Documentation
- MCP Specification: https://modelcontextprotocol.io/specification/2025-11-25
- MCP Registry: https://registry.modelcontextprotocol.io/
- Claude Code MCP Guide: https://code.claude.com/docs/en/mcp

### Package Documentation
- GitHub MCP: https://www.npmjs.com/package/@modelcontextprotocol/server-github
- Filesystem MCP: https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem
- Sequential Thinking MCP: https://www.npmjs.com/package/@modelcontextprotocol/server-sequential-thinking

### Development Resources
- MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk
- MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk
- Example Servers: https://modelcontextprotocol.io/examples

### Community Resources
- Awesome MCP Servers: https://mcpservers.org/
- MCP Cursor Directory: https://cursor.directory/mcp/
- Glama MCP Servers: https://glama.ai/mcp/servers

---

## Maintenance

### Updating MCP Servers

**Automatic Updates:**
- npx automatically fetches latest versions
- No manual update required for npx-based installations

**Manual Version Pinning:**
```json
"args": [
  "-y",
  "@modelcontextprotocol/server-github@1.2.3"
]
```

### Monitoring

- Check Claude Code logs for MCP server errors
- Verify connectivity periodically
- Review token permissions and expiration dates
- Update documentation when adding new servers

---

## Support and Issues

**MCP-Related Issues:**
- Official MCP GitHub: https://github.com/modelcontextprotocol/modelcontextprotocol/issues
- Claude Code Issues: https://github.com/anthropics/claude-code/issues

**ClaudeTools-Specific Issues:**
- Project GitHub: (Add your Gitea repository URL)
- Contact: (Add support contact)

---

**Installation Date:** 2026-01-17
**Configured By:** Claude Code Agent
**Next Review:** 2026-02-17 (30 days)