claudetools/MCP_SERVERS.md

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:

{
  "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:

{
  "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:

  "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:

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

Optional Configuration:

• Disable thought logging: Set environment variable DISABLE_THOUGHT_LOGGING=true
• Example:

  "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:

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:

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:

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:

   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:

{
  "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:

   "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:

"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)