claudetools/MCP_SERVERS.md

MCP Servers Configuration for ClaudeTools

Last Updated: 2026-01-22 Status: Configured and Ready for Testing Phase: Phase 1 - Core MCP Servers + GrepAI Integration

---

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

---

4. GrepAI MCP Server (Semantic Code Search)

Package: grepai (standalone binary) Purpose: AI-powered semantic code search and call graph analysis Status: Configured and Indexing Complete Version: v0.19.0

Capabilities:

• Semantic code search (find code by what it does, not just text matching)
• Natural language queries ("authentication flow", "database connection pool")
• Call graph analysis (trace function callers/callees)
• Symbol extraction and indexing
• Real-time file watching and automatic re-indexing
• JSON output for AI agent integration

Configuration:

{
  "grepai": {
    "command": "D:\\ClaudeTools\\grepai.exe",
    "args": [
      "mcp-serve"
    ]
  }
}

MCP Tools Available:

• grepai_search - Semantic code search with natural language
• grepai_trace_callers - Find all functions that call a specific function
• grepai_trace_callees - Find all functions called by a specific function
• grepai_trace_graph - Build complete call graph for a function
• grepai_index_status - Check index health and statistics

Setup Steps:

1. Install GrepAI Binary:

   curl -L -o grepai.zip https://github.com/yoanbernabeu/grepai/releases/download/v0.19.0/grepai_0.19.0_windows_amd64.zip
   powershell -Command "Expand-Archive -Path grepai.zip -DestinationPath . -Force"
   

2. Install Ollama (if not already installed):

   • Download from: https://ollama.com/download
   • Ollama provides local, privacy-first embedding generation

3. Pull Embedding Model:

   ollama pull nomic-embed-text
   

4. Initialize GrepAI in Project:

   cd D:\ClaudeTools
   ./grepai.exe init
   # Select: 1) ollama (recommended)
   # Select: 1) gob (file-based storage)
   

5. Start Background Watcher:

   ./grepai.exe watch --background
   

   Note: Initial indexing takes 5-10 minutes for large codebases. The watcher runs continuously and updates the index when files change.

6. Add to .mcp.json (already done)

7. Restart Claude Code to load the MCP server

Index Statistics (ClaudeTools):

• Files indexed: 957
• Code chunks: 6,467
• Symbols extracted: 1,842
• Index size: ~50 MB
• Indexing time: ~5 minutes (initial scan)
• Backend: GOB (file-based)
• Embedding model: nomic-embed-text (768 dimensions)

Configuration Details:

• Config file: .grepai/config.yaml
• Index storage: .grepai/ directory
• Log directory: C:\Users\<username>\AppData\Local\grepai\logs\
• Ignored patterns: node_modules, venv, .git, dist, etc.

Search Boost (Enabled): GrepAI automatically adjusts relevance scores:

• Source files (/src/, /lib/, /app/): 1.1x boost
• Test files (_test., .spec.): 0.5x penalty
• Mock files (/mocks/): 0.4x penalty
• Generated files: 0.4x penalty
• Documentation (.md): 0.6x penalty

Usage Examples:

Semantic Search:

# CLI usage
./grepai.exe search "authentication JWT token" -n 5

# JSON output (used by MCP)
./grepai.exe search "database connection pool" --json -c -n 3

Call Graph Tracing:

# Find who calls this function
./grepai.exe trace callers "verify_token"

# Find what this function calls
./grepai.exe trace callees "create_user"

# Full call graph
./grepai.exe trace graph "process_request" --depth 3

Check Index Status:

./grepai.exe status

In Claude Code (via MCP): After restarting Claude Code, you can use natural language:

• "Use grepai to search for authentication code"
• "Find all functions that call verify_token"
• "Search for database connection handling"
• "What code handles JWT token generation?"

Performance:

• Search latency: <100ms (typical)
• Indexing speed: ~200 files/minute
• Memory usage: ~100-200 MB (watcher + index)
• No internet connection required (fully local)

Privacy & Security:

• All embeddings generated locally via Ollama
• No data sent to external services
• Index stored locally in .grepai/ directory
• Safe to use with proprietary code

Troubleshooting:

Issue: No results found

• Wait for initial indexing to complete (check ./grepai.exe status)
• Verify watcher is running: ./grepai.exe watch --status
• Check logs: C:\Users\<username>\AppData\Local\grepai\logs\grepai-watch.log

Issue: Slow indexing

• Ensure Ollama is running: curl http://localhost:11434/api/tags
• Check CPU usage (embedding generation is CPU-intensive)
• Consider reducing chunking size in .grepai/config.yaml

Issue: Watcher won't start

• Check if another instance is running: ./grepai.exe watch --status
• Kill stale process (Windows Task Manager)
• Delete .grepai/watch.pid if stuck

Issue: MCP server not responding

• Verify grepai.exe path in .mcp.json is correct
• Restart Claude Code completely
• Test MCP server manually: ./grepai.exe mcp-serve (should start server)

Advanced Configuration:

Edit .grepai/config.yaml for customization:

embedder:
  provider: ollama           # ollama | lmstudio | openai
  model: nomic-embed-text
  endpoint: http://localhost:11434
  dimensions: 768

store:
  backend: gob              # gob | postgres | qdrant

chunking:
  size: 512                 # Tokens per chunk
  overlap: 50               # Overlap between chunks

search:
  boost:
    enabled: true           # Enable relevance boosting
  hybrid:
    enabled: false          # Combine vector + text search
    k: 60                   # RRF parameter

trace:
  mode: fast                # fast (regex) | precise (tree-sitter)

References:

• GitHub Repository: https://github.com/yoanbernabeu/grepai
• Documentation: https://yoanbernabeu.github.io/grepai/
• MCP Integration Guide: https://yoanbernabeu.github.io/grepai/mcp/
• Release Notes: https://github.com/yoanbernabeu/grepai/releases

---

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

---

Test 4: GrepAI Semantic Search

Test Command:

./grepai.exe search "authentication" -n 3

Expected: Returns 3 relevant code chunks related to authentication

Check Index Status:

./grepai.exe status

Expected: Shows indexed files count, chunks, and index size

In Claude Code (after restart):

• Ask: "Use grepai to search for database connection code"
• Ask: "Find all functions that call verify_token"
• Verify: Claude can perform semantic code search

Note: GrepAI requires Ollama to be running with nomic-embed-text model

---

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)