MCP Servers

Located at project root, version-controlled, shared with team.

Use for:

• Servers needed by the project
• Team-shared integrations
• Project-specific tools

Located in home directory, personal, not version-controlled.

Use for:

• Personal tools and preferences
• API keys and credentials
• Experimental servers

Process-based communication:

{
  "type": "stdio",
  "command": "/path/to/executable",
  "args": ["arg1", "arg2"]
}

Most common type, works with any language that can read stdin/write stdout.

HTTP streaming:

{
  "type": "sse",
  "url": "https://api.example.com/mcp"
}

For cloud-hosted MCP servers.

Traditional HTTP requests:

{
  "type": "http",
  "url": "https://api.example.com/mcp"
}

For REST-style MCP servers.

Provides deep Emacs integration for context-aware coding assistance.

Installation:

# Clone the MCP Emacs server
git clone https://github.com/your-org/mcp-emacs.git
cd mcp-emacs

# Create virtual environment and install
python -m venv venv
source venv/bin/activate
pip install -e .

# Start Emacs daemon if not already running
emacs --daemon

Configuration: Update the paths in .mcp.json above to point to:

• Your mcp-emacs installation directory
• The Python executable in the venv
• The server.py script path

Capabilities:

Buffer Operations:

• get_buffer_content - Read buffer contents
• list_buffers - List all open buffers
• open_file - Open files in Emacs
• get_current_context - Get cursor position and context

LSP Integration:

• lsp_hover - Get documentation at cursor
• lsp_diagnostics - Get errors and warnings
• lsp_completion - Get code completions
• lsp_definition - Jump to definitions
• lsp_references - Find all references
• lsp_rename - Rename symbols
• lsp_format - Format code
• lsp_code_actions - Get available fixes
• lsp_document_symbols - Get file outline
• lsp_workspace_symbols - Search for symbols

Project Management:

• list_projects - List known projects
• get_current_project - Get active project
• switch_project - Switch to different project

Org-Mode:

• org_agenda_todos - Get TODO items from agenda
• org_capture - Create capture entries
• org_get_file_todos - Get TODOs from specific file

File Proposals:

• propose_file_change - Propose edits with ediff review
• apply_proposed_change - Apply after review
• reject_proposed_change - Reject and clean up

Compilation:

• compile_project - Run build command
• get_compilation_errors - Get structured error list
• recompile - Re-run last compilation
• kill_compilation - Stop running compilation

Use Cases:

• Context-aware code explanations (knows your cursor position)
• Emacs-specific assistance (knows your config, buffers, projects)
• LSP-powered refactoring (rename, format, fix)
• Org file management (capture TODOs, manage agenda)
• Safe file editing with ediff review

Provides safe filesystem access restricted to the project directory.

Installation: No installation needed - uses npx to run on-demand.

Configuration: The server is restricted to the project root directory specified in args[2].

Capabilities:

• Read files within allowed paths
• Write files with proper permissions
• List directory contents
• Get file metadata (size, modified time, etc.)
• Safe operations (can't escape allowed paths)

Security:

• Access restricted to specified directory
• No access outside project root
• Safe for team sharing in version control
• Prevents accidental system file access

Use Cases:

• Project-scoped file operations
• Safe file manipulation
• Directory traversal within project
• Metadata queries

Configuration: Update args[2] to your project's absolute path. The current value is already set for this project.

Interact with GitHub repositories, PRs, and issues.

{
  "github": {
    "type": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-github"
    ],
    "env": {
      "GITHUB_TOKEN": "your-token-here"
    }
  }
}

Capabilities:

• List and search repositories
• Create and manage issues
• Review and comment on pull requests
• Search code across repositories
• Manage branches and commits

Setup:

1. Create GitHub personal access token
2. Set GITHUB_TOKEN environment variable
3. Add to ~/.claude.json

Web research and real-time information.

{
  "perplexity": {
    "type": "sse",
    "url": "https://api.perplexity.ai/mcp",
    "env": {
      "PERPLEXITY_API_KEY": "your-key-here"
    }
  }
}

Capabilities:

• Web search with citations
• Up-to-date information
• Technical documentation lookup
• Research assistance

Enhanced reasoning and problem-solving.

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

Capabilities:

• Break down complex problems
• Step-by-step reasoning
• Structured problem solving
• Task decomposition

Access to up-to-date technical documentation.

{
  "context7": {
    "type": "sse",
    "url": "https://api.context7.com/mcp",
    "env": {
      "CONTEXT7_API_KEY": "your-key-here"
    }
  }
}

Capabilities:

• Latest framework documentation
• API references
• Package documentation
• Version-specific docs

Privacy-focused web search.

{
  "brave-search": {
    "type": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-brave-search"
    ],
    "env": {
      "BRAVE_API_KEY": "your-key-here"
    }
  }
}

Capabilities:

• Web search
• News search
• Image search
• Video search

Database access and queries.

{
  "postgres": {
    "type": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-postgres"
    ],
    "env": {
      "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/dbname"
    }
  }
}

Capabilities:

• Execute SQL queries
• Inspect database schema
• Manage tables and data
• Database introspection

Security: Only use in personal config, never commit credentials.

• stdio: Best for local tools, any language
• SSE: For cloud-hosted servers
• HTTP: For REST-style services

Minimal server structure:

from mcp.server import Server, NotificationOptions
from mcp.server.models import InitializationOptions
import mcp.server.stdio
import mcp.types as types

# Create server
server = Server("my-server")

# Define capabilities
@server.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="my_tool",
            description="What this tool does",
            inputSchema={
                "type": "object",
                "properties": {
                    "param": {"type": "string"}
                }
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
    if name == "my_tool":
        result = do_something(arguments["param"])
        return [types.TextContent(type="text", text=result)]

# Run server
async def main():
    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            InitializationOptions(
                server_name="my-server",
                server_version="1.0.0"
            )
        )

Each tool needs:

• name: Unique identifier
• description: When/how to use it
• inputSchema: JSON Schema for parameters
• handler: Function that executes the tool

• Python: PyPI package
• Node: NPM package
• Other: Docker image or binary