Geo MCP Server

MCP server providing full access to the Geo protocol SDK for knowledge graph operations. Build, query, and publish structured knowledge to the Geo decentralized knowledge network using the GRC-20 standard.

Features

• 38 tools covering the full Geo SDK surface: read, write, and govern

• GraphQL read layer - search entities, browse spaces, query proposals and votes

• DAO governance - vote on proposals, propose editor/subspace changes

• Session-based op accumulation - build complex edits across multiple tool calls, then publish as a single atomic transaction

• Publish-to-propose continuity - propose_dao_edit can reuse the latest published ops for seamless publish_edit -> propose_dao_edit flows

• Name-based resolution - reference properties, types, and entities by name instead of IDs

• Gas-sponsored smart accounts - no testnet ETH needed (uses Pimlico paymaster)

• Secure local file ingestion - load local JSON/markdown/text files from allowlisted paths

Related MCP server: Universal Ontology MCP

Installation

npm install
npm run build

Configuration

Add to your MCP client config (e.g. Claude Code .mcp.json):

{
  "mcpServers": {
    "geo": {
      "command": "node",
      "args": ["/path/to/geo-mcp-server/dist/index.js"],
      "env": {
        "GEO_PRIVATE_KEY": "0x...",
        "GEO_MCP_ALLOWED_PATHS": "/Users/me/Documents/research,/tmp"
      }
    }
  }
}

The GEO_PRIVATE_KEY environment variable is optional at startup - you can also configure the wallet at runtime using the configure_wallet tool. GEO_MCP_ALLOWED_PATHS is optional and lets you allow additional directories for read_local_file and create_knowledge_graph_from_file. By default, only the current working directory is allowed. GEO_GRAPHQL_URL optionally overrides the GraphQL API endpoint (default: https://testnet-api.geobrowser.io/graphql).

Quick Start

Typical workflow:

1. Configure wallet - configure_wallet with your private key

2. Setup space - setup_space creates or finds your personal space

3. Build knowledge - use any graph tools to create properties, types, entities, and relations

4. Publish - publish_edit sends all accumulated ops on-chain in one transaction

Example: Create a Knowledge Graph in One Call

Use create_knowledge_graph for the best UX - it builds schema, entities, and relations all at once with name-based references:

create_knowledge_graph({
  schema: {
    properties: [
      { name: "Founded", dataType: "DATE" },
      { name: "Website", dataType: "TEXT" }
    ],
    types: [
      { name: "Company", propertyNames: ["Founded", "Website"] }
    ]
  },
  entities: [
    {
      name: "Geo",
      typeName: "Company",
      values: [
        { propertyName: "Founded", type: "date", value: "2024-01-01" },
        { propertyName: "Website", type: "text", value: "https://geo.xyz" }
      ]
    }
  ]
})

Example: Publish a Local Graph Payload File

When your extraction pipeline writes a JSON payload locally, use one call to ingest it:

create_knowledge_graph_from_file({
  filePath: "./outputs/claimify-paper-graph.json"
})

Expected JSON shape inside the file:

• { "schema": { ... }, "entities": [...], "relations": [...] }

• or { "payload": { "schema": { ... }, "entities": [...], "relations": [...] } }

Tools Reference

Graph Operations (8 tools)

Space & Publishing (6 tools)

Advanced UX (7 tools)

Read & Query (10 tools)

DAO Governance (5 tools)

Supported Data Types

TEXT, INTEGER, FLOAT, BOOLEAN, DATE, TIME, DATETIME, SCHEDULE, POINT, DECIMAL, BYTES, EMBEDDING, RELATION

Development

npm run dev        # Run with tsx (hot reload)
npm run build      # Compile TypeScript
npm run typecheck  # Type check without emitting
npm start          # Run compiled version
npm test           # Run unit tests
npm run test:watch # Run tests in watch mode

Network

Currently operates on the Geo testnet.

License

MIT