RDF4J MCP Server

Explore knowledge graphs with Claude - A Model Context Protocol (MCP) server that enables AI-powered exploration of RDF data and SPARQL querying.

Quick Demo

Try it out in under 2 minutes:

# 1. Clone and install
git clone https://github.com/your-org/rdf4j-mcp.git
cd rdf4j-mcp
uv sync  # or: pip install -e .

# 2. Start RDF4J + load sample data
./examples/setup-demo.sh

# 3a. Run as local MCP server (stdio)
rdf4j-mcp --server-url http://localhost:8081/rdf4j-server --repository demo

# 3b. Or run as remote HTTP server
rdf4j-mcp-server --port 3000 --server-url http://localhost:8081/rdf4j-server --repository demo

Then try these prompts with Claude:

"What classes and properties are in this knowledge graph?"

"Find all people and the projects they work on"

"Show me the project with the highest budget"

Installation

Prerequisites: Python 3.11+, Docker (for RDF4J)

git clone https://github.com/your-org/rdf4j-mcp.git
cd rdf4j-mcp
uv sync  # or: pip install -e .

Two Ways to Run

Command	Transport	Use Case
rdf4j-mcp	stdio	MCP client spawns locally (Claude Desktop, VS Code)
rdf4j-mcp-server	HTTP/SSE	Standalone remote server, multiple clients

Option 1: Local Mode (stdio)

The MCP client spawns the server as a local process:

rdf4j-mcp --server-url http://localhost:8080/rdf4j-server --repository my-repo

Option 2: Remote Mode (HTTP/SSE)

Run as a standalone HTTP server:

# Start the server
rdf4j-mcp-server --port 3000 \
  --server-url http://localhost:8080/rdf4j-server \
  --repository my-repo

# Or with environment variables
export RDF4J_MCP_RDF4J_SERVER_URL=http://localhost:8080/rdf4j-server
export RDF4J_MCP_DEFAULT_REPOSITORY=my-repo
rdf4j-mcp-server --port 3000

# Or with uvicorn (production)
uvicorn rdf4j_mcp.main:app --host 0.0.0.0 --port 3000 --workers 4

Endpoints:

• GET /sse - SSE endpoint for MCP clients
• GET /health - Health check
• GET /info - Server configuration

Client Configuration

Claude Desktop

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Local mode (stdio):

{
  "mcpServers": {
    "rdf4j": {
      "command": "rdf4j-mcp",
      "args": ["--server-url", "http://localhost:8080/rdf4j-server", "--repository", "my-repo"]
    }
  }
}

Remote mode (HTTP):

{
  "mcpServers": {
    "rdf4j": {
      "url": "http://your-server:3000/sse"
    }
  }
}

VS Code

Create .vscode/mcp.json in your workspace:

Local mode:

{
  "servers": {
    "rdf4j": {
      "command": "rdf4j-mcp",
      "args": ["--server-url", "http://localhost:8080/rdf4j-server", "--repository", "my-repo"]
    }
  }
}

Remote mode:

{
  "servers": {
    "rdf4j": {
      "url": "http://your-server:3000/sse"
    }
  }
}

For GitHub Copilot, use @mcp in chat:

@mcp What classes are in the knowledge graph?

Features

MCP Tools

Tool	Description
sparql_select	Execute SELECT queries, returns JSON
sparql_construct	Execute CONSTRUCT/DESCRIBE, returns Turtle
sparql_ask	Execute ASK queries, returns boolean
describe_resource	Get all triples about an IRI
search_classes	Find classes by name pattern
search_properties	Find properties by pattern/domain/range
find_instances	Find instances of a class
get_schema_summary	Ontology overview with statistics
list_repositories	List available repositories
get_namespaces	Get namespace prefix mappings
get_statistics	Statement/class/property counts
select_repository	Switch active repository

MCP Resources

URI	Description
rdf4j://repositories	List of repositories
rdf4j://repository/{id}/schema	Schema summary
rdf4j://repository/{id}/namespaces	Namespace prefixes
rdf4j://repository/{id}/statistics	Repository statistics

MCP Prompts

Prompt	Description
explore_knowledge_graph	Guided exploration with schema context
write_sparql_query	Natural language to SPARQL
explain_ontology	Explain classes and relationships

Configuration

CLI Options

rdf4j-mcp (stdio mode):

--server-url URL    RDF4J server URL (default: http://localhost:8080/rdf4j-server)
--repository ID     Default repository ID
--debug             Enable debug logging

rdf4j-mcp-server (HTTP mode):

--host HOST         Bind address (default: 0.0.0.0)
--port PORT         Listen port (default: 3000)
--server-url URL    RDF4J server URL
--repository ID     Default repository ID
--reload            Auto-reload for development
--debug             Enable debug logging

Environment Variables

All use the RDF4J_MCP_ prefix:

Variable	Default	Description
RDF4J_SERVER_URL	http://localhost:8080/rdf4j-server	RDF4J server URL
DEFAULT_REPOSITORY	-	Default repository ID
QUERY_TIMEOUT	30	Query timeout (seconds)
DEFAULT_LIMIT	100	Default query LIMIT
MAX_LIMIT	10000	Maximum query LIMIT

Running RDF4J Server

Using Docker:

docker run -d -p 8080:8080 eclipse/rdf4j-workbench

Then create a repository at http://localhost:8080/rdf4j-workbench.

Or use the demo setup script which handles everything:

./examples/setup-demo.sh

Development

uv sync --dev

# Run tests
pytest

# Lint and format
ruff check src tests
ruff format src tests

# Type check
ty check src

License

MIT