Talk to your Anytype knowledge base in plain language from
AI assistants like Claude, Cursor, and any other
MCP client.
This is a self-hosted fork of the official
anyproto/anytype-mcp that adds a
Docker container and a Streamable-HTTP transport, so the server can run
quietly in the background and be reached by any MCP client over HTTP. (The
original speaks stdio only.)
Why this one?
The official Anytype MCP server is
great, but it runs as a stdio subprocess that each client has to launch on
demand. This project keeps 100% of its capabilities and adds a
production-style deployment: one always-on server, in Docker, that any
number of MCP clients can reach over HTTP.
Capability
This project
Official anyproto/anytype-mcp
Other community servers*
Full Anytype API coverage (dynamic OpenAPI → MCP tools)
✅
✅
✅
stdio transport
✅
✅
✅
Streamable-HTTP transport (native, or via mcp-remote)
In short: if you just want to try Anytype from your AI client, the official
server is perfect. If you want it running in the background, always ready, and
shared across every MCP client on your machine, use this one.
What you can do
Once it's connected, ask your assistant things like:
"Search my Anytype for notes about the Q3 launch."
"Create a task 'Write the report', due in 3 days."
"Make a new space called 'Travel' and add a packing checklist."
Tools are generated automatically from your running Anytype app and grouped into
🟢 read-only, 🟡 write, and 🔴 delete.
The server is tuned to keep your assistant fast and frugal with tool calls:
API-get-overview — a synthesized tool that returns all spaces with their
types (or, given a space_id, that space's types and property definitions) in
a single call, instead of a list-spaces → list-types → list-properties cascade.
Slim responses — API payloads are compacted before they reach the
assistant: empty property values, object discriminators, and nulls are
dropped, and the type embedded in each search/list result is reduced to its
identifiers. This typically shrinks list/search responses by well over half,
which means less context burned per call and fewer follow-up calls. Set
ANYTYPE_MCP_SLIM_RESPONSES=false to get raw API payloads instead.
Routing hints — tool descriptions tell the assistant which tool is
cheapest for a job (e.g. search instead of paginating lists, and that only
get-object returns the full markdown body).
How it works
Claude / Cursor / … ──MCP──► this server ──HTTP──► Anytype desktop app (local API)
The server only talks to the local API of the Anytype desktop app on
your own machine. Your data stays on your computer.
Requirements
The Anytype desktop app, installed and running (it serves a local API at
127.0.0.1:31009).
Docker (Docker Desktop on macOS/Windows) for the setup below.
Quick start (Docker)
1. Add your API key. Copy the example config and paste in a key:
cp .env.example .env
# open .env and set ANYTYPE_API_KEY=... (see "Get an API key" below)
Why not npx -y mcp-remote …?npx re-resolves the package through the npm
cache on every launch. When a client cold-starts several MCP servers at once they
contend on that cache, and some launchers can wedge inside npx for minutes —
which the client reports as a connection timeout. Installing mcp-remote once and
launching it with node removes that step. Use absolute paths (GUI apps don't
inherit your shell PATH, and mcp-remote's own #!/usr/bin/env node shebang
can't find node otherwise). The paths above are Apple-Silicon Homebrew defaults;
adjust with which node and npm root -g if yours differ.
That's it — ask your assistant to search or create something in Anytype.
Get an API key
In the Anytype desktop app: Settings → API Keys → Create new. Copy the key
into .env as ANYTYPE_API_KEY=. Your key stays in .env, which git ignores,
so it is never committed.
Configuration
Everything is set in .env (copied from .env.example):
Variable
Default
What it does
ANYTYPE_API_KEY
—
Your Anytype API key. Required.
ANYTYPE_VERSION
2025-11-08
Anytype API version header.
ANYTYPE_API_BASE_URL
http://host.docker.internal:31009
Where the Anytype app's API is reachable from the container.
ANYTYPE_API_HOST_HEADER
(auto)
Host header sent to the Anytype API. Auto-set to localhost:<port> when the base URL uses a container host alias, because Anytype rejects any other Host with 403 request origin is not allowed.
PORT
8769
Host port for the MCP endpoint.
MCP_SHARED_TOKEN
(empty)
Optional bearer token to protect the endpoint. Empty = open, for localhost only.
ANYTYPE_MCP_SLIM_RESPONSES
true
Compact API responses before sending them to the assistant. Set to false for raw payloads.
After changing .env, reload with docker compose up -d --force-recreate.
For logs, restart, key rotation, and verification commands, see
DOCKER.md.
Run from source (stdio, no Docker)
Prefer the classic stdio mode? Build it locally:
npm install
npm run build
Then register it with your client using a stdio command and your key in
OPENAPI_MCP_HEADERS — see the
upstream README for the exact
stdio configuration.
Security
Your API key lives only in .env, which is git-ignored. Never commit real keys.
The HTTP endpoint is unauthenticated by default (fine on localhost). To expose
it beyond your machine, set MCP_SHARED_TOKEN and send it as a Bearer header
or ?token=….
MCP Registry
This server publishes to the official
MCP Registry under the name
io.github.ohneben/anytype-mcp. To look up the current listing:
Its listing is described by server.json and is republished
automatically on every v*.*.* tag by
.github/workflows/publish-mcp.yml,
which waits for the matching GHCR image and authenticates with GitHub OIDC (no
secret needed). The registry proves the image is ours via the
io.modelcontextprotocol.server.name label in the Dockerfile,
so the GHCR package must stay Public.
Releasing
The git tag is the version. Pushing v1.2.3 is the whole release: the tag
is stamped into package.json before the image is built and into server.json
before the listing is published, so the version the server reports to MCP
clients, the image tag, and the registry entry cannot disagree. Nothing needs to
be bumped by hand first, and the versions committed here are only the defaults
used by local builds.
