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.
One URL: page + MCPAccount-controlled accessStreamable 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 the site through the Model Context Protocol. ChatGPT can sign in through OAuth, while developer clients can use a personal token. Current account permissions and ownership rules are checked for every request.
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 ChatGPT with account sign-in, or Codex, Claude Code, Hermes Agent and OpenClaw with your own token. Available data and actions follow your account permissions.
How to Connect
Choose your client and connect it to the same /mcp URL. ChatGPT uses OAuth sign-in; clients that accept custom headers can use a personal token.
One connection URL
For ChatGPT, select “OAuth or no authentication” and sign in with your existing Minecraft.How account. For developer clients, create a personal token in API Access. Both methods apply your current account permissions.
Manage my API tokensServer endpoint
https://minecraft.how/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/mcp"
bearer_token_env_var = "MINECRAFT_HOW_TOKEN"These examples contain placeholders only. Store the real token in your client’s private configuration. For CLI examples, set MINECRAFT_HOW_TOKEN in your local environment. Never put a token in a public repository or URL.
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 show my available resources and actions. Do not make any changes.Ideas for your next conversation
Use these prompts in ChatGPT, Claude, Codex or another connected MCP client.
01 · Personal token
Find 5 Bedrock servers on Minecraft.How and include the address and source URL for each.02 · Personal token
Search Minecraft.How for skins named knight. Show 5 options with image links.03 · Personal token
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
Tool discovery follows the permissions selected for the token. Account permissions and ownership rules are checked again when each tool runs.
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
get_blog_posts
Read blog posts allowed by the token and current account permissions.
Parameters: locale, published, category_id, limit, offset
get_minecraft_versions
Read stored Minecraft release and snapshot information for fact checking.
Parameters: type, is_latest, limit
get_tickets
List support tickets when the token and account both have support viewing access.
Parameters: status, priority, search, limit
get_ticket
Read one support ticket and its conversation within the permitted scope.
Parameters: ticket_id
create_ticket
Create a support request with a subject, message and contact email.
Parameters: subject, message, contact_email, priority
reply_to_ticket
Reply to a permitted ticket and optionally queue the contact email requested by the user.
Parameters: ticket_id, message, send_email
update_ticket
Update permitted ticket status or priority when support editing access is available.
Parameters: ticket_id, status, priority
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
Catalog protection
Catalog tools return permitted fields only. Hidden skins, private servers and unrelated account records stay excluded.
Your account, your scope
120 requests/minute per user. Up to 50 records per account query. Your current account access and, when used, personal token permissions decide which operations are available. 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 token-permitted MCP tools with a JSON-RPC POST request. Replace the token placeholder and keep the real value private.
JSON-RPC · curl
curl --fail-with-body 'https://minecraft.how/mcp' \
-H 'Authorization: Bearer YOUR_PERSONAL_TOKEN' \
-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 the MCP endpoint open this web page in my browser?
The same /mcp URL serves both uses. A browser sends GET and receives this presentation page. An MCP client sends an authenticated JSON-RPC POST request and receives the protocol response.
Why can my agent not see a record or perform an action?
Check the endpoint, your current account access and, for personal tokens, their permissions and expiry. A connection never grants more access than your account has. Start with get_project_capabilities to inspect the available operations.
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. It can use the OAuth discovery flow or 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 or revoked. 403 means the token or account cannot access that resource or action. For 429, wait for the Retry-After interval before trying again.
Setup guides reviewed: October 19, 2026