Gowler/FoundryVTT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
15355c35ea57949443ffac8cf6f04d20bcbf7d78
FoundryVTT/MCP_SERVERS_GUIDE.md
Claude Code 15355c35ea Initial commit: Fresh start with current state
2025-11-06 14:04:48 +01:00

37 KiB
Raw Blame History

MCP Servers - Complete Guide

Comprehensive documentation for all Model Context Protocol (MCP) servers used in Claude Code Version: 1.0.0 | Last Updated: 2025-10-20

Table of Contents

  1. Overview
  2. Quick Start
  3. Installation & Setup
  4. Available MCP Servers
  5. Usage Guide
  6. Configuration
  7. Best Practices
  8. Troubleshooting
  9. Advanced Topics

Overview

What Are MCP Servers?

Model Context Protocol (MCP) servers extend Claude Code's capabilities by providing:

  • External integrations (databases, browsers, desktop automation)
  • Enhanced code navigation and analysis
  • Persistent and temporary memory systems
  • Real-time documentation access
  • Complex reasoning capabilities

MCP Servers in This Project

This project includes 8 fully configured MCP servers:

# Server Type Purpose
1 Serena Python (uvx) Code navigation + persistent memory
2 Sequential Thinking Node.js (npx) Complex reasoning engine
3 Database Server Node.js (npx) SQL Server integration
4 Context7 Node.js (npx) Library documentation
5 Memory Node.js (npx) Knowledge graph (session)
6 Fetch Python (uvx) Web content retrieval
7 Windows MCP Python (uv) Desktop automation
8 Playwright Node.js (npx) Browser automation

MCP vs Core Tools

Core Tools (built-in):

  • Read, Write, Edit - File operations
  • Glob, Grep - File search
  • Bash - Shell commands
  • WebSearch, WebFetch - Web access

MCP Servers (extended):

  • Semantic code navigation
  • Persistent knowledge storage
  • Complex reasoning
  • Browser/desktop automation
  • Database access

Quick Start

One-Command Setup

Windows (PowerShell):

.\.claude\tools\setup-all-mcp-servers.ps1

Linux/Mac (Bash):

./.claude/tools/setup-all-mcp-servers.sh

Verify Installation

# Test all servers
.\.claude\tools\test-mcp-servers.ps1

# Or check individual servers
claude mcp list
claude mcp test serena

Quick Test

# In Claude Code
> "Use Serena to find the UserService class"
> "Create a knowledge graph of the authentication flow"
> "Get the latest React documentation"

Installation & Setup

Prerequisites

The setup script checks for and guides installation of:

  1. Node.js (v18+) - For npm-based servers

  2. Python 3 (3.8+) - For Python-based servers

  3. uv - Python package manager

    • Auto-installed by setup script
    • Manual: curl -LsSf https://astral.sh/uv/install.sh | sh

  4. Git (optional, recommended)

Automated Setup Process

The setup script:

  1. ✅ Checks prerequisites
  2. ✅ Installs all 8 MCP servers
  3. ✅ Creates required directories
  4. ✅ Validates configuration
  5. ✅ Provides next steps

Time Required: ~5-10 minutes

Manual Installation

If automated setup fails, install servers individually:

Serena

uvx --from "git+https://github.com/oraios/serena" serena --help

Sequential Thinking

npx -y @modelcontextprotocol/server-sequential-thinking

Database Server

npx -y @executeautomation/database-server

Context7

npx -y @upstash/context7-mcp

Memory

npx -y @modelcontextprotocol/server-memory

Fetch

uvx mcp-server-fetch

Windows MCP

git clone https://github.com/lekt9/windows-mcp.git .windows-mcp
cd .windows-mcp
uv sync

Playwright

npx -y @playwright/mcp
npx playwright install  # Install browsers

Post-Setup Configuration

After running setup, configure secrets:

1. Enable MCP Servers

Already configured in .claude/settings.json:

{
  "enableAllProjectMcpServers": true
}

2. Context7 API Key (Optional)

Edit .mcp.json:

"context7": {
  "env": {
    "CONTEXT7_API_KEY": "your-api-key-here"
  }
}

Get key at: https://context7.com/

3. Database Connection (Optional)

Edit .mcp.json:

"database-server": {
  "args": [
    "--server", "your-server",
    "--database", "your-database",
    "--user", "your-username",
    "--password", "your-password",
    "--trustServerCertificate"
  ]
}

4. Restart Claude Code

Close and reopen Claude Code to load servers.

Available MCP Servers

1. Serena MCP

Purpose: Semantic code analysis and persistent memory

Type: Python (uvx)

Repository: https://github.com/oraios/serena

Configuration:

{
  "command": "uvx",
  "args": [
    "--from", "git+https://github.com/oraios/serena",
    "serena", "start-mcp-server",
    "--context", "ide-assistant",
    "--project", "Claude Code Setup"
  ]
}

Code Navigation Tools

find_symbol - Locate code symbols by name/pattern

# Find a class
find_symbol("UserService")

# Find with pattern
find_symbol("*Service")

# Find with depth (include methods)
find_symbol("UserService", depth=1, include_body=true)

find_referencing_symbols - Find all references to a symbol

# Find who uses this function
find_referencing_symbols("authenticate", "src/auth/service.ts")

get_symbols_overview - Get file structure

# Get high-level view of file
get_symbols_overview("src/services/user.ts")

search_for_pattern - Search for code patterns

# Find pattern across codebase
search_for_pattern("async.*await", paths_include_glob="**/*.ts")

rename_symbol - Safely rename across codebase

# Rename everywhere
rename_symbol("oldName", "src/file.ts", "newName")

replace_symbol_body - Replace function/class body

# Replace entire method
replace_symbol_body("methodName", "src/file.ts", new_body)

insert_after_symbol / insert_before_symbol - Add code

# Add new method after existing one
insert_after_symbol("existingMethod", "src/file.ts", new_method_code)

Persistent Memory Tools

Storage: .serena/memories/ (survives across sessions)

write_memory - Store persistent project information

write_memory("adr-001-architecture", "Decision: Use microservices...")

read_memory - Recall stored information

read_memory("adr-001-architecture")

list_memories - Browse all memories

list_memories()

delete_memory - Remove outdated information

delete_memory("outdated-info")

Use Serena Memory For

✅ Long-term project knowledge:

  • Architectural Decision Records (ADRs)
  • Code review findings and summaries
  • Lessons learned from implementations
  • Project-specific patterns discovered
  • Technical debt registry
  • Security audit results
  • Performance optimization notes
  • Migration documentation
  • Incident post-mortems

❌ Do NOT use for:

  • Temporary analysis state
  • Current conversation context
  • Session-specific tracking

Memory File Naming Conventions

ADRs (Architectural Decision Records):

adr-001-database-choice-postgresql
adr-002-authentication-jwt-strategy
adr-003-api-versioning-approach

Code Reviews:

code-review-2024-10-15-payment-service
code-review-2025-10-20-auth-refactor

Lessons Learned:

lesson-async-error-handling
lesson-database-connection-pooling
lesson-api-rate-limiting

Patterns:

pattern-repository-implementation
pattern-error-response-format
pattern-logging-strategy

Technical Debt:

debt-legacy-api-authentication
debt-payment-service-refactor-needed

Security:

security-audit-2024-10-full
security-vulnerability-xss-fixed
security-pattern-input-validation

Performance:

performance-optimization-query-caching
performance-analysis-api-endpoints

2. Sequential Thinking MCP

Purpose: Chain-of-thought reasoning for complex problems

Type: Node.js (npx)

Package: @modelcontextprotocol/server-sequential-thinking

Configuration:

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

Capabilities

sequentialthinking - Multi-step reasoning tool

Features:

  • Dynamic thought count adjustment
  • Revision of previous thoughts
  • Branch exploration
  • Hypothesis generation and verification
  • Flexible problem-solving

Parameters:

  • thought - Current thinking step
  • thought_number - Current step number
  • total_thoughts - Estimated total (adjustable)
  • next_thought_needed - Continue or stop
  • is_revision - Is this revising previous thought
  • branch_id - Identifier for exploration branches

Use Cases

✅ Best for:

  • Complex architectural decisions
  • Multi-step debugging
  • Design pattern selection
  • Security threat analysis
  • Algorithm optimization
  • System design problems

Example Flow:

  1. Start with initial estimate of needed thoughts
  2. Work through problem step-by-step
  3. Revise previous thoughts if needed
  4. Adjust total thoughts as understanding deepens
  5. Generate hypothesis
  6. Verify hypothesis
  7. Provide final answer

3. Database Server MCP

Purpose: SQL Server database interaction

Type: Node.js (npx)

Package: @executeautomation/database-server

Configuration:

{
  "command": "npx",
  "args": [
    "-y", "@executeautomation/database-server",
    "--sqlserver",
    "--server", "your-server",
    "--database", "your-database",
    "--user", "your-username",
    "--password", "your-password",
    "--trustServerCertificate"
  ]
}

Available Tools

read_query - Execute SELECT queries

SELECT * FROM Users WHERE active = 1

write_query - Execute INSERT, UPDATE, DELETE

UPDATE Users SET last_login = GETDATE() WHERE id = 123

create_table - Create new tables

CREATE TABLE Products (
  id INT PRIMARY KEY,
  name VARCHAR(255),
  price DECIMAL(10,2)
)

alter_table - Modify table schema

ALTER TABLE Products ADD description TEXT

drop_table - Remove tables (with confirmation)

drop_table("old_table", confirm=true)

list_tables - Get all tables in database

list_tables()

describe_table - View table schema

describe_table("Users")

export_query - Export results to CSV/JSON

export_query("SELECT * FROM Users", format="csv")

append_insight - Add business insight to memo

append_insight("Sales increased 20% after new feature")

list_insights - View all insights

list_insights()

Use Cases

✅ Best for:

  • Database schema exploration
  • Query development and testing
  • Data analysis
  • Business intelligence
  • Database migrations
  • Performance testing

4. Context7 MCP

Purpose: Real-time library documentation access

Type: Node.js (npx)

Package: @upstash/context7-mcp

Website: https://context7.com/

Configuration:

{
  "command": "npx",
  "args": ["-y", "@upstash/context7-mcp"],
  "env": {
    "CONTEXT7_API_KEY": "your-api-key-here"
  }
}

Available Tools

resolve-library-id - Find library identifier

# Find library ID
resolve-library-id("react")
# Returns: "/facebook/react"

resolve-library-id("next.js")
# Returns: "/vercel/next.js"

Selection Criteria:

  • Name similarity (exact matches prioritized)
  • Description relevance
  • Documentation coverage (code snippets count)
  • Trust score (7-10 prioritized)

get-library-docs - Get current documentation

# Get React docs
get-library-docs("/facebook/react", topic="hooks")

# Get specific version
get-library-docs("/vercel/next.js/v14.3.0", topic="routing")

# Control token usage
get-library-docs("/mongodb/docs", tokens=10000)

Parameters:

  • context7CompatibleLibraryID - Library ID from resolve-library-id
  • topic - Focus area (optional)
  • tokens - Max tokens (default: 5000)

Use Cases

✅ Best for:

  • Learning new frameworks
  • Getting up-to-date API references
  • Finding best practices
  • Code examples from official docs
  • Version-specific documentation

Example Workflow:

# 1. Find library
resolve-library-id("supabase")

# 2. Get docs
get-library-docs("/supabase/supabase", topic="authentication")

# 3. Use in code
# Claude now has current Supabase auth docs

5. Memory MCP (Knowledge Graph)

Purpose: Temporary in-memory knowledge graph

Type: Node.js (npx)

Package: @modelcontextprotocol/server-memory

Storage: In-memory, cleared after session ends

Configuration:

{
  "command": "powershell",
  "args": [
    "-ExecutionPolicy", "Bypass",
    "-File", ".\.claude\tools\start-memory.ps1"
  ]
}

Available Tools

create_entities - Create entities in graph

create_entities([
  {
    name: "PaymentService",
    entityType: "Service",
    observations: [
      "Handles Stripe integration",
      "Located in src/services/payment.ts",
      "Depends on DatabaseService"
    ]
  },
  {
    name: "UserAuthentication",
    entityType: "Feature",
    observations: [
      "Uses JWT tokens",
      "Session timeout: 24 hours"
    ]
  }
])

create_relations - Define relationships

create_relations([
  {
    from: "PaymentService",
    to: "DatabaseService",
    relationType: "depends_on"
  },
  {
    from: "UserAuthentication",
    to: "SessionManager",
    relationType: "uses"
  }
])

add_observations - Add details to entities

add_observations([
  {
    entityName: "PaymentService",
    contents: [
      "Implemented retry logic",
      "Added webhook support"
    ]
  }
])

search_nodes - Search knowledge graph

search_nodes("payment")

read_graph - View entire graph

read_graph()

open_nodes - Retrieve specific entities

open_nodes(["PaymentService", "UserAuthentication"])

delete_entities - Remove entities

delete_entities(["OldFeature"])

delete_relations - Remove relationships

delete_relations([
  {from: "A", to: "B", relationType: "uses"}
])

delete_observations - Remove specific observations

delete_observations([
  {
    entityName: "PaymentService",
    observations: ["outdated info"]
  }
])

Use Cases

✅ Best for:

  • Current conversation context
  • Temporary analysis during task
  • Entity relationships in current work
  • Cross-file refactoring state (temporary)
  • Session-specific tracking

❌ Do NOT use for:

  • Long-term knowledge (use Serena instead)
  • ADRs or lessons learned
  • Project patterns
  • Anything needed next week

Memory vs Serena Decision Tree

Question: Should this information exist next week?

  • YES → Use Serena write_memory
  • NO → Use Memory graph

Storage Location: .memory-mcp/knowledge_graph.json (managed by PowerShell script)

6. Fetch MCP

Purpose: Web content retrieval and conversion

Type: Python (uvx)

Package: mcp-server-fetch

Configuration:

{
  "command": "uvx",
  "args": ["mcp-server-fetch"]
}

Available Tools

fetch - Retrieve and process URLs

Parameters:

  • url - URL to fetch (required)
  • max_length - Max characters (default: 5000)
  • start_index - Start position (for pagination)
  • raw - Get raw HTML instead of markdown

Features:

  • Converts HTML to markdown
  • Pagination support for long content
  • Automatic HTTPS upgrade
  • Self-cleaning 15-minute cache

Examples:

# Fetch documentation
fetch("https://docs.example.com/api")

# Get raw HTML
fetch("https://example.com", raw=true)

# Paginated content
fetch("https://long-page.com", start_index=5000, max_length=5000)

Use Cases

✅ Best for:

  • API documentation scraping
  • Web content analysis
  • Integration documentation
  • Blog post research
  • Technical article retrieval

Note: When URL redirects to different host, tool informs you. Make new request with redirect URL.

7. Windows MCP

Purpose: Windows desktop automation

Type: Python (uv)

Repository: https://github.com/lekt9/windows-mcp

Platform: Windows only (won't affect other servers on Mac/Linux)

Configuration:

{
  "command": "uv",
  "args": [
    "--directory", "./.windows-mcp",
    "run", "main.py"
  ]
}

Available Tools

Launch-Tool - Launch applications

Launch-Tool("notepad")
Launch-Tool("calculator")
Launch-Tool("chrome")

Powershell-Tool - Execute PowerShell commands

Powershell-Tool("Get-Process | Where-Object {$_.Name -like 'chrome*'}")

State-Tool - Capture desktop state

# Get UI elements, focused apps, interactive elements
State-Tool(use_vision=false)

# Include visual screenshot
State-Tool(use_vision=true)

Clipboard-Tool - Clipboard operations

# Copy text
Clipboard-Tool(mode="copy", text="Hello World")

# Paste (retrieve)
Clipboard-Tool(mode="paste")

Click-Tool - Click UI elements

# Left click at coordinates
Click-Tool(loc=[100, 200])

# Right click
Click-Tool(loc=[100, 200], button="right")

# Double click
Click-Tool(loc=[100, 200], clicks=2)

Type-Tool - Type text into fields

# Type text (append)
Type-Tool(loc=[100, 200], text="Hello")

# Clear and type
Type-Tool(loc=[100, 200], text="Hello", clear=true)

# Type and press Enter
Type-Tool(loc=[100, 200], text="search query", press_enter=true)

Resize-Tool - Resize/move windows

# Resize window
Resize-Tool(size=[800, 600])

# Move window
Resize-Tool(loc=[100, 100])

Switch-Tool - Switch to application

Switch-Tool("notepad")
Switch-Tool("chrome")

Scroll-Tool - Scroll content

# Scroll down at location
Scroll-Tool(loc=[400, 300], direction="down", wheel_times=3)

# Scroll horizontally
Scroll-Tool(type="horizontal", direction="right")

Drag-Tool - Drag and drop

Drag-Tool(from_loc=[100, 100], to_loc=[200, 200])

Move-Tool - Move mouse cursor

Move-Tool(to_loc=[300, 400])

Shortcut-Tool - Keyboard shortcuts

# Copy
Shortcut-Tool(["ctrl", "c"])

# Alt+Tab
Shortcut-Tool(["alt", "tab"])

# Windows+R
Shortcut-Tool(["win", "r"])

Key-Tool - Press individual keys

Key-Tool("enter")
Key-Tool("escape")
Key-Tool("f5")

Wait-Tool - Pause execution

Wait-Tool(duration=5)  # Wait 5 seconds

Scrape-Tool - Scrape webpage to markdown

Scrape-Tool("https://example.com")

Use Cases

✅ Best for:

  • GUI automation
  • Desktop testing
  • Windows-specific operations
  • Application interaction
  • Screen automation workflows

8. Playwright MCP

Purpose: Browser automation and testing

Type: Node.js (npx)

Package: @playwright/mcp

Website: https://playwright.dev/

Configuration:

{
  "command": "npx",
  "args": ["-y", "@playwright/mcp"]
}

Additional Setup: Run npx playwright install to install browsers

Available Tools

Navigation:

  • browser_navigate - Navigate to URL
  • browser_navigate_back - Go back

Interaction:

  • browser_click - Click elements
  • browser_type - Type text
  • browser_fill_form - Fill multiple form fields
  • browser_select_option - Select dropdown options
  • browser_hover - Hover over elements
  • browser_drag - Drag and drop

Keyboard:

  • browser_press_key - Press keys
  • browser_evaluate - Execute JavaScript

Capture:

  • browser_snapshot - Accessibility snapshot (better than screenshot)
  • browser_take_screenshot - Take visual screenshot

Monitoring:

  • browser_console_messages - Get console logs
  • browser_network_requests - View network traffic

Window Management:

  • browser_tabs - Manage tabs (list, create, close, select)
  • browser_resize - Resize browser window
  • browser_close - Close browser

Advanced:

  • browser_file_upload - Upload files
  • browser_handle_dialog - Handle alerts/confirms
  • browser_wait_for - Wait for conditions

Usage Examples

Basic Navigation:

// Navigate and capture
browser_navigate("https://example.com")
browser_snapshot()

// Take screenshot
browser_take_screenshot(filename="page.png")

Form Interaction:

// Fill form
browser_fill_form([
  {name: "username", type: "textbox", ref: "input#user", value: "john"},
  {name: "password", type: "textbox", ref: "input#pass", value: "secret"},
  {name: "remember", type: "checkbox", ref: "input#rem", value: "true"}
])

// Click submit
browser_click(element="Submit button", ref="button[type='submit']")

Testing Workflow:

// 1. Navigate
browser_navigate("https://app.example.com/login")

// 2. Fill and submit
browser_type(element="Username field", ref="input#user", text="test@example.com")
browser_type(element="Password field", ref="input#pass", text="password")
browser_click(element="Login button", ref="button.login")

// 3. Wait and verify
browser_wait_for(text="Welcome")
browser_snapshot()

// 4. Check network
browser_network_requests()

Tab Management:

// List tabs
browser_tabs(action="list")

// Create new tab
browser_tabs(action="new")

// Switch to tab
browser_tabs(action="select", index=1)

// Close tab
browser_tabs(action="close", index=2)

Use Cases

✅ Best for:

  • E2E testing
  • Web scraping
  • UI automation
  • Browser-based workflows
  • Screenshot capture
  • Network monitoring
  • Console debugging

Usage Guide

Quick Decision Tree

Need to navigate code? → Use Serena code functions

Need to store knowledge long-term? → Use Serena write_memory

Building temporary context for current task? → Use Memory graph

Need current library docs? → Use Context7

Complex problem requiring deep thought? → Use Sequential Thinking

Need to automate browser? → Use Playwright

Need Windows desktop automation? → Use Windows MCP

Need to query database? → Use Database Server

Need to scrape web content? → Use Fetch

Usage by Agent Type

Architect Agent

## MCP Usage

**Serena**:
- `get_symbols_overview` - Understand current architecture
- `find_symbol` - Locate key components
- `write_memory` - Store ADRs:
  - "adr-001-microservices-architecture"
  - "adr-002-database-choice-postgresql"

**Memory**:
- `create_entities` - Components being designed
- `create_relations` - Model dependencies
- `add_observations` - Document design rationale

Note: After design finalized, store in Serena memory as ADR

Code Reviewer Agent

## MCP Usage

**Serena**:
- `find_symbol` - Locate reviewed code
- `find_referencing_symbols` - Impact analysis
- `write_memory` - Store review findings:
  - "code-review-2024-10-payment-service"

**Memory**:
- `create_entities` - Issues found (Critical, Warning, Suggestion)
- `create_relations` - Link issues to code locations
- `add_observations` - Fix recommendations

Note: Summary stored in Serena memory after review

Security Analyst Agent

## MCP Usage

**Serena**:
- `find_symbol` - Locate security-sensitive code
- `search_for_pattern` - Find potential vulnerabilities
- `write_memory` - Store audit results:
  - "security-audit-2024-10-full-scan"
  - "vulnerability-sql-injection-fixed"

**Memory**:
- `create_entities` - Vulnerabilities found
- `create_relations` - Link to affected code
- `add_observations` - Document severity and remediation

Test Engineer Agent

## MCP Usage

**Serena**:
- `find_symbol` - Locate code to test
- `find_referencing_symbols` - Understand dependencies
- `write_memory` - Store test patterns:
  - "test-pattern-async-handlers"
  - "test-pattern-database-mocking"

**Memory**:
- `create_entities` - Test cases being generated
- `create_relations` - Link tests to code under test

**Playwright**:
- Browser testing automation

Usage in Slash Commands

/implement Command

## MCP Usage

**Serena**:
- `find_symbol` - Locate existing patterns
- `find_referencing_symbols` - Understand dependencies
- `rename_symbol` - Refactor safely
- `write_memory` - Store lessons:
  - "lesson-payment-integration-stripe"
  - "pattern-error-handling-async"

**Memory**:
- `create_entities` - Track features being implemented
- `create_relations` - Model integration points

**Context7**:
- `get-library-docs` - Current framework docs

/analyze Command

## MCP Usage

**Serena**:
- `get_symbols_overview` - Understand structure
- `find_symbol` - Locate complex code
- `search_for_pattern` - Find duplicates
- `write_memory` - Store findings:
  - "analysis-2024-10-technical-debt"
  - "analysis-complexity-hotspots"

**Memory**:
- `create_entities` - Files/functions analyzed
- `create_relations` - Model dependencies
- `add_observations` - Document metrics

Configuration

Main Configuration File

Location: .mcp.json (project root)

Format:

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/oraios/serena",
        "serena", "start-mcp-server",
        "--context", "ide-assistant",
        "--project", "ProjectName"
      ]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "database-server": {
      "command": "npx",
      "args": [
        "-y", "@executeautomation/database-server",
        "--sqlserver",
        "--server", "server-name",
        "--database", "db-name",
        "--user", "username",
        "--password", "password",
        "--trustServerCertificate"
      ]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {
        "CONTEXT7_API_KEY": "your-key"
      }
    },
    "memory": {
      "command": "powershell",
      "args": [
        "-ExecutionPolicy", "Bypass",
        "-File", ".\.claude\tools\start-memory.ps1"
      ]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "windows-mcp": {
      "command": "uv",
      "args": [
        "--directory", "./.windows-mcp",
        "run", "main.py"
      ]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

Claude Settings Configuration

Location: .claude/settings.json

Enable MCP Servers:

{
  "enableAllProjectMcpServers": true
}

Enable Specific Servers:

{
  "mcpServers": {
    "serena": {"enabled": true},
    "memory": {"enabled": true},
    "context7": {"enabled": true}
  }
}

Environment Variables

Context7 API Key:

# Option 1: In .mcp.json (not recommended for git)
"env": {"CONTEXT7_API_KEY": "ctx7sk-..."}

# Option 2: System environment variable (recommended)
export CONTEXT7_API_KEY="ctx7sk-..."

Database Credentials:

# Use environment variables for security
export DB_SERVER="server-name"
export DB_USER="username"
export DB_PASSWORD="password"

# Reference in .mcp.json
"args": ["--server", "${DB_SERVER}", "--user", "${DB_USER}"]

Best Practices

Memory Management

Use Serena Memory For:

  • ✅ Architectural Decision Records
  • ✅ Code review summaries
  • ✅ Lessons learned
  • ✅ Project patterns
  • ✅ Technical debt tracking
  • ✅ Security findings
  • ✅ Performance notes

Use Memory Graph For:

  • ✅ Current conversation context
  • ✅ Temporary analysis state
  • ✅ Session-specific tracking
  • ✅ Cross-file refactoring state

DON'T Mix Them:

  • ❌ Don't store temporary info in Serena
  • ❌ Don't expect Memory graph to persist

Code Navigation Efficiency

Good Practice (efficient):

# 1. Get overview first
get_symbols_overview("src/service.ts")

# 2. Target specific symbols
find_symbol("UserService/authenticate", include_body=true)

# 3. Find references if needed
find_referencing_symbols("authenticate", "src/service.ts")

Bad Practice (wasteful):

# Reading entire files unnecessarily
Read("src/service.ts")  # 1000 lines
Read("src/utils.ts")    # 500 lines
Read("src/auth.ts")     # 800 lines

Documentation Lookup Pattern

Correct Workflow:

# 1. Always resolve library ID first
resolve-library-id("react")
# Returns: /facebook/react

# 2. Then get docs
get-library-docs("/facebook/react", topic="hooks")

Incorrect (won't work):

# Don't skip resolve step
get-library-docs("react")  # ERROR: not a valid ID

Browser Automation Best Practices

Use Snapshots, Not Screenshots:

# Good: Accessibility snapshot (faster, more data)
browser_snapshot()

# Use screenshots only when visual verification needed
browser_take_screenshot()

Wait for Content:

# Good: Wait for specific text
browser_wait_for(text="Welcome")

# Avoid arbitrary delays
browser_wait_for(time=5)  # Use only when necessary

Database Query Safety

Always Use Parameterized Queries:

-- Good
SELECT * FROM Users WHERE id = @userId

-- Bad (SQL injection risk)
SELECT * FROM Users WHERE id = ${userInput}

Test Before Write:

# 1. Test with read_query
read_query("SELECT * FROM Users WHERE ...")

# 2. Verify results

# 3. Then write_query
write_query("UPDATE Users SET ...")

Troubleshooting

MCP Server Not Starting

Problem: Server fails to connect

Solutions:

  1. Check .mcp.json syntax:

    cat .mcp.json | jq .

  2. Test command manually:

    npx -y @modelcontextprotocol/server-memory
uvx mcp-server-fetch

  3. Check Claude Code logs:

    • Windows: .claude\logs\
    • Linux/Mac: .claude/logs/

  4. Verify prerequisites installed:

    node --version  # Should be 18+
python --version  # Should be 3.8+
npm --version
uv --version

  5. Restart Claude Code after config changes

Serena Memory Not Persisting

Problem: Memories disappear between sessions

Check:

  1. Verify storage location exists:

    ls .serena/memories/

  2. Check memory was actually written:

    list_memories()

  3. Ensure using write_memory, not Memory graph:

    # Correct (persists)
write_memory("my-memory", "content")

# Wrong (session only)
create_entities([{name: "my-memory", ...}])

Memory Graph Empty After Restart

This is normal! Memory graph is session-only storage.

If you need persistence: Use Serena write_memory instead.

Context7 Not Working

Problem: Library docs not retrieved

Solutions:

  1. Check API key configured:

    cat .mcp.json | jq '.mcpServers.context7.env'

  2. Get free API key: https://context7.com/

  3. Always resolve library ID first:

    # Required first step
resolve-library-id("library-name")

  4. Use correct ID format:

    # Correct
get-library-docs("/facebook/react")

# Wrong
get-library-docs("react")

Playwright Browsers Not Installed

Problem: Browser automation fails

Solution:

npx playwright install
npx playwright install chromium  # Just Chromium

Verify:

npx playwright --version

Windows MCP Not Working on Mac/Linux

This is normal! Windows MCP is Windows-only.

It won't break other servers - they'll continue working.

On Mac/Linux: Simply ignore Windows MCP server errors.

Database Connection Failed

Problem: Cannot connect to SQL Server

Solutions:

  1. Verify connection details:

    # Test connection manually
sqlcmd -S server -U user -P password -d database

  2. Check .mcp.json configuration:

    "--server", "correct-server-name",
"--database", "correct-db-name",
"--user", "correct-username",
"--password", "correct-password"

  3. Add --trustServerCertificate if using self-signed certs

  4. Check network connectivity and firewall rules

Permission Errors

Problem: MCP server command denied

Solutions:

  1. Check file permissions:

    # Linux/Mac
chmod +x .claude/tools/*.sh

# Windows PowerShell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

  2. Verify tool allowed in .claude/settings.json:

    {
  "permissions": {
    "allowed": ["mcp__serena__*", "mcp__memory__*"]
  }
}

Command Not Found (npx/uvx)

Problem: Setup script can't find package managers

Solutions:

  1. Install Node.js: https://nodejs.org/

  2. Install Python and uv:

    curl -LsSf https://astral.sh/uv/install.sh | sh

  3. Restart terminal after installation

  4. Verify installation:

    npx --version
uvx --version

Advanced Topics

Custom MCP Server Configuration

You can add your own MCP servers to .mcp.json:

{
  "mcpServers": {
    "my-custom-server": {
      "command": "node",
      "args": ["./my-server/index.js"],
      "env": {
        "MY_CONFIG": "value"
      }
    }
  }
}

MCP Server Development

Create custom MCP servers:

Performance Optimization

Parallel MCP Calls:

# Claude can call multiple MCP servers in parallel
# when operations are independent

Token Efficiency:

  • Use Serena symbols instead of full file reads
  • Use Memory graph for temporary context
  • Leverage Grep/Glob before reading

Caching:

  • Context7 and Fetch have built-in caching
  • Memory graph caches for session duration

Security Considerations

Secrets Management:

  • ❌ Never commit API keys to git
  • ✅ Use environment variables
  • ✅ Use .claude/settings.local.json (gitignored)

Database Access:

  • Use read-only accounts when possible
  • Parameterize all queries
  • Audit database operations

Browser Automation:

  • Be cautious with authentication in Playwright
  • Don't expose credentials in screenshots
  • Review captured network requests

Integration with CI/CD

Headless Mode (optional):

# Run Claude Code in CI pipeline
claude --headless --session ci-build

# Use MCP servers in automation
# Example: Database migrations, E2E tests

Updating MCP Servers

Update All Servers:

# Re-run setup script (idempotent)
.\.claude\tools\setup-all-mcp-servers.ps1

Update Individual Server:

# npm-based servers (auto-update with -y flag)
npx -y @modelcontextprotocol/server-memory

# Python-based servers
uvx --from "git+https://github.com/oraios/serena" serena

# Windows MCP (git-based)
cd .windows-mcp
git pull
uv sync

Monitoring and Logging

Check Server Status:

claude mcp list
claude mcp test <server-name>

View Logs:

# All logs
ls .claude/logs/

# MCP-specific logs
cat .claude/logs/mcp-*.log

Debug Mode: Add to .claude/settings.json:

{
  "debug": true,
  "logLevel": "debug"
}

Additional Resources

Official Documentation

Project Documentation

Setup Scripts

Summary

This guide covers all 8 MCP servers configured in this project:

  1. ✅ Serena - Code navigation + persistent memory
  2. ✅ Sequential Thinking - Complex reasoning
  3. ✅ Database Server - SQL Server integration
  4. ✅ Context7 - Library documentation
  5. ✅ Memory - Knowledge graph (session)
  6. ✅ Fetch - Web content retrieval
  7. ✅ Windows MCP - Desktop automation
  8. ✅ Playwright - Browser automation

Quick Commands Reference

# Setup
.\.claude\tools\setup-all-mcp-servers.ps1

# Test
.\.claude\tools\test-mcp-servers.ps1

# Check status
claude mcp list
claude mcp test <server-name>

# View logs
cat .claude/logs/mcp-*.log

Key Takeaways

  • Serena Memory = Long-term knowledge (persists)
  • Memory Graph = Session-only context (temporary)
  • Context7 = Real-time library docs (requires API key)
  • Playwright = Browser automation (requires browser install)
  • Windows MCP = Windows-only (safe to ignore on Mac/Linux)

Version: 1.0.0 Last Updated: 2025-10-20 Maintained by: Claude Code Setup Project

For latest information: See official documentation at https://docs.claude.com/en/docs/claude-code/

This comprehensive guide consolidates all MCP server documentation from multiple sources into a single reference. For setup automation, see the tools in .claude/tools/.

Reference in New Issue View Git Blame Copy Permalink