search_servers
Find public listings by name, address, edition, category or supported Minecraft version.
Parameters: query, platform, category, version, limit
Minecraft MCP Server
Bring Minecraft servers, skins and your project workflow into the AI tools you already use.
Guest: read onlyPersonal: your permissionsStreamable HTTP
Codex · Claude · Cursor · VS Code · ChatGPT · Hermes · OpenClaw
Model Context Protocol
Minecraft data, inside your AI conversation
Minecraft.How MCP connects AI assistants to our Minecraft server and skin catalog through the Model Context Protocol. Search public listings without an account, or connect your own token for account data and supported management actions. The agent receives structured results and source links it can use in its answer.
Find your next server
Compare Java, Bedrock and crossplay listings by name, category or version. Check addresses and the latest stored player counts.
Find a Minecraft skin
Search public skins by name and get the listing and image URLs. Keep useful results in the same conversation.
Connect your own agent
Use Codex, Claude Code, Hermes Agent or OpenClaw with your own token. Available data and actions follow your account permissions.
How to Connect
Choose your access level and client. Copy the configuration, enable the server, then try your first prompt.
No account or API key required. Public servers and skins only. Limited to 30 requests per minute per IP and 20 results per search.
Server endpoint
https://minecraft.how/api/mcpCodex / Setup
- 1Open your Codex configuration file and add the server block below.
- 2For personal access, set MINECRAFT_HOW_TOKEN in the environment used to launch Codex.
- 3Start a new Codex session and use /mcp to check the server and available tools.
~/.codex/config.toml
[mcp_servers.minecraft-how]
url = "https://minecraft.how/api/mcp"Run your first call
Paste this into your connected AI and check that it calls a Minecraft.How tool, rather than answering from memory.
Run your first call
Use Minecraft.How MCP to find 5 Java survival servers. Include their source links and the time of the latest status check when available.Ideas for your next conversation
Use these prompts in ChatGPT, Claude, Codex or another connected MCP client.
01 · Guest · read only
Find 5 Bedrock servers on Minecraft.How and include the address and source URL for each.02 · Guest · read only
Search Minecraft.How for skins named knight. Show 5 options with image links.03 · Guest · read only
Get the details of the first server in those results. Is its stored status online or offline?04 · Personal token
Show which Minecraft.How resources my personal token can read and which actions it can perform.Minecraft MCP tools
The guest connection exposes these four read-only tools. Personal connections add account tools, with authorization checked on every call.
get_server_details
Look up a server returned by search, including its address, stored status and source URL.
Parameters: server_id
search_skins
Find public Minecraft skins by name, ordered by downloads.
Parameters: query, limit
get_skin_details
Get a visible skin’s details, listing URL and image URL.
Parameters: skin_id
Tools for your personal agent
get_project_capabilities lists your available resources and actions. read_project_data returns permitted records with pagination. manage_project_record delegates supported changes to the site’s existing validation and controllers.
Blog workflows can also use get_blog_posts, get_content_opportunities and get_minecraft_versions. Internal content opportunities require the agents.blog.view permission. Guest access never includes these tools.
Access and permissions
Public discovery
30 requests/minute per IP. Up to 20 results per search. Hidden skins, private servers and account data are excluded.
Your account, your scope
120 requests/minute per user. Up to 50 records per account query. Token scopes restrict access; Spatie permissions decide which operations you can perform. Ownership limits apply to personal records.
Control from API Access
Create a token per agent, set an expiry, and revoke it at any time. Removing a user’s permission also removes that permission from their MCP connection.
Make a direct API call
For developers: list the public MCP tools with a JSON-RPC POST request. MCP clients handle protocol initialization automatically; this stateless endpoint also accepts the direct discovery call below.
JSON-RPC · curl
curl --fail-with-body 'https://minecraft.how/api/mcp' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-11-25' \
--data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'Connection questions
Does this let an AI play Minecraft or run commands on my server?
No. This MCP server provides Minecraft.How catalog data and permitted site-management actions. It does not join a Minecraft world, access your game files, expose a shell or provide RCON access.
Why does opening the endpoint in my browser show 405?
The endpoint accepts MCP requests over HTTP POST. A browser address bar sends GET, which returns 405 Method Not Allowed. Use an MCP client or the API example above to test the connection.
Why can my agent not see a record or perform an action?
Check the endpoint, token scopes, token expiry and your current account permissions. A token never grants additional Spatie permissions. Start with get_project_capabilities to inspect the access available to your account.
Are the server player counts live?
They reflect the latest stored server check, not a new ping triggered by your prompt. Check last_ping when comparing results. Offline server results omit stale player counts.
Can I use a client other than those listed?
Yes, if it supports remote MCP over Streamable HTTP. For personal access it must also support a Bearer token in the Authorization header. Configuration names vary between clients.
What should I do with 401, 403 or 429 errors?
401 means the token is missing, expired, revoked or lacks mcp:read. 403 means your account cannot access that resource or action. For 429, wait for the Retry-After interval before trying again.
Setup guides reviewed: October 19, 2026