MCP Server

velocirepo includes a built-in Model Context Protocol (MCP) server, allowing AI assistants like Claude to query your metrics, trigger fetches, and manage projects conversationally.

Starting the server

velocirepo mcp                          # stdio (for Claude Desktop / Claude Code)
velocirepo mcp --http 127.0.0.1:8080    # Streamable HTTP
velocirepo mcp --read-only              # Disable fetch/write tools

Claude Desktop configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "velocirepo": {
      "command": "velocirepo",
      "args": ["mcp", "--config", "/path/to/velocirepo.toml"]
    }
  }
}

Claude Code configuration

Add to your project’s .mcp.json:

{
  "mcpServers": {
    "velocirepo": {
      "command": "velocirepo",
      "args": ["mcp"]
    }
  }
}

Available tools

Tool Description
query Run SQL against metrics, events, content, projects views
schema Show all table columns and types
fetch Fetch from all configured sources
fetch_github Fetch GitHub events
fetch_traffic Fetch GitHub traffic
fetch_pypi Fetch PyPI downloads
fetch_cran Fetch CRAN downloads
fetch_homebrew Fetch Homebrew installs
fetch_plausible Fetch Plausible analytics
fetch_openvsx Fetch Open VSX metrics
fetch_youtube Fetch YouTube metrics
fetch_linkedin Fetch LinkedIn post metrics and content
list_projects List configured projects
show_project Show project details and fetch stats
add_project Add a project to the config
update_project Update project configuration
remove_project Remove a project
rename_project Rename a project ID
import_projects Bulk-import from GitHub org/user
validate_projects Check that source URLs are reachable
list_views List all views with framework and source
show_view Show view details
add_view Scaffold a new view
remove_view Remove a view
render_view Render a single view
render_views Render all or filtered views
badge Generate an SVG badge
export Export data to Parquet or CSV
migrate Migrate data to latest schema
version Show version info

Query tool limits

The query tool wraps every SQL statement in an outer LIMIT clause to protect against accidentally returning very large result sets.

Parameter Behaviour
limit not set defaults to 1 000 rows
limit <= 0 treated as the default (1 000 rows)
limit > 10 000 capped at 10 000 rows

To retrieve more than 10 000 rows, use the export tool, which writes Parquet or CSV files without a row limit.

Export tool restrictions

The export tool writes files relative to the project directory (the directory that contains velocirepo.toml). Absolute paths, .. traversals, and symlinks that escape the project directory are rejected.

Example prompts

Once connected, you can ask things like:

  • “Which project got the most stars this month?”
  • “Show me PyPI download trends for plotnine over the last 6 months”
  • “Fetch the latest metrics for all projects”
  • “Add a new project called ‘my-lib’ tracking pypi package my-lib and github owner/my-lib”
  • “Generate a stars badge for quarto”

Next steps