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

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)

Tool	Description
create_property	Create a property definition with a data type
create_type	Create a type (schema) grouping properties
create_entity	Create an entity with types, values, and relations
create_relation	Create a relation between two entities
create_image	Create an image entity from a URL
update_entity	Update an existing entity's name, values, or properties
delete_entity	Delete an entity
delete_relation	Delete a relation

Space & Publishing (6 tools)

Tool	Description
configure_wallet	Set up wallet with a private key for publishing
setup_space	Create or find your personal space
publish_edit	Publish all accumulated ops as one on-chain edit
propose_dao_edit	Propose accumulated ops as a DAO governance edit
get_session_status	View current session state (ops count, artifacts, wallet)
clear_session	Discard all accumulated ops

Advanced UX (7 tools)

Tool	Description
generate_id	Generate one or more unique Geo IDs (dashless UUID v4)
build_schema	Create properties + types in one call with name-based references
create_knowledge_graph	Build complete graph (schema + entities + relations) in one call
create_knowledge_graph_from_file	Build complete graph from a local JSON file payload
read_local_file	Read local text/json/binary (base64) from allowlisted paths
add_values_to_entity	Add multiple property values to an existing entity
get_system_ids	Get well-known Geo system IDs (types, properties, data types)

Read & Query (10 tools)

Tool	Description
search_entities	Full-text search for entities with optional space/type filters
get_entity	Get full entity details (values, relations, backlinks, types)
list_entities	Browse entities with filters for space, type, and name
get_space	Get space details with editor/member counts and recent proposals
list_spaces	Browse spaces with optional type filter (PERSONAL/DAO)
get_type	Get type definition with properties
list_types	List types in a specific space
get_proposals	List proposals for a space (newest first)
get_proposal	Get full proposal details with vote breakdown
get_proposal_votes	List votes for a specific proposal

DAO Governance (5 tools)

Tool	Description
vote_on_proposal	Cast YES/NO/ABSTAIN vote on a DAO proposal
propose_accept_editor	Propose adding a new editor to a DAO space
propose_remove_editor	Propose removing an editor from a DAO space
propose_accept_subspace	Propose accepting a subspace into a DAO space
propose_remove_subspace	Propose removing a subspace from a DAO space

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