Symbols MCP Server

An MCP (Model Context Protocol) server that exposes the Symbols/DOMQL v3 AI assistant capabilities to any MCP-compatible platform — Cursor, Claude Code, Windsurf, and more.

Features

Tools

Resources

Prompts

Installation

Quick Start (No API Keys Required!)

1. Clone the repository:

git clone https://github.com/baronsilver/symbols-mcp-server.git
cd symbols-mcp-server

1. Install dependencies:

pip install uv
uv sync
npm i @symbo.ls/cli -g
smbls create your-project

IMPORTANT: For now, delete the docs folder inside your project folder after creation

1. Configure:

cp .env.example .env
# Edit .env and add both:
# - SYMBOLS_MCP_URL (contact maintainer for public server URL)
# - LLM_MODEL=google/gemini-3-flash-preview

Platform Integration

Claude Code

claude mcp add symbols-mcp -- uv run --directory C:\repos\symbols-mcp-server symbols-mcp

Or manually edit ~/UserName/.claude.json:

{
  "mcpServers": {
    "symbols-mcp": {
      "command": "python",
      "args": [
        "-m",
        "uv",
        "run",
        "--directory",
        "C:\\repos\\symbols-mcp-server",
        "symbols-mcp"
      ]
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project or global settings):

{
  "mcpServers": {
    "symbols-mcp": {
      "command": "python",
      "args": [
        "-m",
        "uv",
        "run",
        "--directory",
        "C:\\repos\\symbols-mcp-server",
        "symbols-mcp"
      ]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "symbols-mcp": {
      "command": "python",
      "args": [
        "-m",
        "uv",
        "run",
        "--directory",
        "C:\\repos\\symbols-mcp-server",
        "symbols-mcp"
      ]
    }
  }
}

Development

Restart your platforms after updating the MCP settings. Once loaded, it should automatically run the MCP. Ask your AI to do the quick test with the MCP to see if it works properly.

Environment Variables

Architecture

symbols-mcp-server/
├── pyproject.toml              # Project config and dependencies
├── .env.example                # Environment variable template
├── README.md                   # This file
└── symbols_mcp/
    ├── __init__.py
    ├── server.py               # MCP server with tools, resources, prompts
    └── skills/                 # Bundled Symbols knowledge base
        ├── CLAUDE.md           # DOMQL v3 complete reference
        ├── SYMBOLS_LOCAL_INSTRUCTIONS.md  # Project structure rules
        ├── DESIGN_DIRECTION.md # UI/UX design direction
        ├── MIGRATE_TO_SYMBOLS.md # Framework migration guide
        ├── DOMQL_v2-v3_MIGRATION.md # v2→v3 changes
        └── QUICKSTART.md       # CLI quickstart

The server reads skills files at startup and uses them as context for all AI-powered tools. When Supabase is configured, the search_symbols_docs tool also queries the vector database for additional documentation matches.