mcpbridge

One YAML file. Any data source. Instant MCP server.

mcpbridge turns a YAML config file into a working MCP server — no code required.

Point it at a database, a REST API, or a folder of Markdown files. Claude (or any MCP client) can query them immediately.

---

What It Does

• db_query — run parameterized SQL queries against PostgreSQL, SQLite, or MySQL
• get_endpoint — call any REST GET endpoint and expose the result as an MCP tool
• knowledge_base — serve .md files or directories as MCP resources

All three can live in a single config.yaml. Swap the YAML, restart — done.

---

5-Minute Quickstart

With npx (no install)

# 1. Create a config file
cat > config.yaml << 'EOF'
server:
  name: weather-mcp
  version: 1.0.0
  transport: stdio

sources:
  - type: get_endpoint
    name: get_weather
    description: >
      Returns current weather for a location given latitude and longitude.
      Use when the user asks about weather or temperature.
    url: https://api.open-meteo.com/v1/forecast
    query_params:
      - name: latitude
        type: float
        required: true
      - name: longitude
        type: float
        required: true
    response_field: current_weather
EOF

# 2. Validate it
npx mcpbridge validate config.yaml

# 3. Add to Claude Desktop (see below) and ask: "What's the weather in Amsterdam?"

With Docker

docker run \
  -v ./config.yaml:/app/config.yaml \
  --env-file .env \
  mcpbridge/mcpbridge

---

Claude Desktop Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["mcpbridge", "run", "/absolute/path/to/config.yaml"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
      }
    }
  }
}

---

YAML Reference

db_query — SQL query as MCP tool

- type: db_query
  name: get_orders               # snake_case, becomes tool name
  description: >                 # LLM reads this — be specific about when to use it
    Returns all orders for a specific user.
    Use when asked about order history or purchases.
  query: >
    SELECT id, product, amount, status
    FROM orders
    WHERE user_id = :user_id
  params:
    - name: user_id
      type: integer              # string | integer | boolean | float
      required: true
  connection: "${DATABASE_URL}"  # always an env var — never hardcode
  allow_write: false             # default: false — set true only for explicit write tools

Supported databases: PostgreSQL (postgresql://), MySQL (mysql://), SQLite (sqlite://./path.db)

Read-only by default. INSERT/UPDATE/DELETE/DROP are blocked unless allow_write: true. DDL (DROP/ALTER/CREATE) is always blocked.

---

get_endpoint — REST GET as MCP tool

- type: get_endpoint
  name: get_weather
  description: >
    Returns current weather forecast for a given latitude and longitude.
    Use when the user asks about weather or temperature.
  url: https://api.open-meteo.com/v1/forecast
  query_params:
    - name: latitude
      type: float
      required: true
    - name: longitude
      type: float
      required: true
  headers:
    Authorization: "Bearer ${API_KEY}"   # env var substitution in headers too
  response_field: current_weather        # optional: extract nested field (dot notation)
  timeout: 30                            # seconds, default: 30

---

knowledge_base — Markdown files as MCP resources

- type: knowledge_base
  name: company_faq
  description: >
    Internal company FAQ and policies.
    Use when the user asks about company procedures or rules.
  path: ./kb/                    # file or directory (recursive)
  strategy: chunk                # full | chunk
  chunk_size: 800                # chars per chunk (default: 800)
  chunk_overlap: 100             # overlap between chunks (default: 100)

Hidden files (.hidden.md) and directories (.git/) are skipped automatically.

---

Full Example Config

server:
  name: my-company-mcp
  version: 1.0.0
  transport: stdio

sources:
  - type: get_endpoint
    name: get_weather
    description: >
      Returns current weather for a location.
      Use when the user asks about weather.
    url: https://api.open-meteo.com/v1/forecast
    query_params:
      - name: latitude
        type: float
        required: true
      - name: longitude
        type: float
        required: true
    response_field: current_weather

  - type: db_query
    name: get_orders
    description: >
      Returns orders for a specific user.
      Use when the user asks about their order history.
    query: "SELECT id, product, amount, status FROM orders WHERE user_id = :user_id"
    params:
      - name: user_id
        type: integer
        required: true
    connection: "${DATABASE_URL}"

  - type: knowledge_base
    name: company_faq
    description: >
      Company FAQ and internal policies.
      Use when the user asks about company procedures.
    path: ./kb/
    strategy: chunk
    chunk_size: 800

---

Running Locally

# Install
npm install -g mcpbridge
# or without installing:
npx mcpbridge

# Validate a config
mcpbridge validate config.yaml

# Run the server
DATABASE_URL=sqlite://./dev.db mcpbridge run config.yaml

Running with Docker

# Build locally
docker build -t mcpbridge .

# Run with a config
docker run \
  -v ./config.yaml:/app/config.yaml \
  -v ./kb:/app/kb \
  --env-file .env \
  mcpbridge

# Or with docker-compose (includes PostgreSQL)
docker compose up

---

Security Notes

• Secrets always via env vars. The YAML schema rejects connection strings not using ${ENV_VAR} syntax.
• Read-only DB by default. Set allow_write: true explicitly per source to enable mutations.
• DDL is never allowed. DROP/ALTER/CREATE/TRUNCATE are blocked regardless of allow_write.
• No auth on the MCP server in v0.1 — run behind a firewall or VPN. Auth is on the v0.2 roadmap.

---

Let Claude Configure It For You

1. Share your CLAUDE.md with Claude (or just point Claude at this repo)
2. Say: "Configure mcpbridge for my [restaurant / e-commerce store / SaaS app]. Here's what it does: ..."
3. Claude generates a complete config.yaml and .env.example
4. Run mcpbridge validate config.yaml to verify, then deploy

---

Contributing

See CONTRIBUTING.md.

Roadmap

See ROADMAP.md.

License

MIT — see LICENSE.