{"id":50615541,"url":"https://github.com/straps-eq/eqemu-mcp-server","last_synced_at":"2026-06-06T08:01:40.773Z","repository":{"id":355043693,"uuid":"1226554268","full_name":"straps-eq/eqemu-mcp-server","owner":"straps-eq","description":"MCP server for EverQuest Emulator servers — 60+ tools for AI-assisted server management, quest development, and database inspection","archived":false,"fork":false,"pushed_at":"2026-05-01T15:21:41.000Z","size":58,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T16:28:01.076Z","etag":null,"topics":["ai-tools","docker","emulator","eqemu","everquest","game-server","mcp","mcp-server","model-context-protocol"],"latest_commit_sha":null,"homepage":"https://docs.eqemu.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/straps-eq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-01T14:50:02.000Z","updated_at":"2026-05-01T15:21:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/straps-eq/eqemu-mcp-server","commit_stats":null,"previous_names":["straps-eq/eqemu-mcp-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/straps-eq/eqemu-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/straps-eq%2Feqemu-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/straps-eq%2Feqemu-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/straps-eq%2Feqemu-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/straps-eq%2Feqemu-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/straps-eq","download_url":"https://codeload.github.com/straps-eq/eqemu-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/straps-eq%2Feqemu-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33973868,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","docker","emulator","eqemu","everquest","game-server","mcp","mcp-server","model-context-protocol"],"created_at":"2026-06-06T08:01:37.809Z","updated_at":"2026-06-06T08:01:40.752Z","avatar_url":"https://github.com/straps-eq.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/version-0.4.0-blue\" alt=\"Version\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.10+-green\" alt=\"Python\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-orange\" alt=\"License\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/tools-60+-purple\" alt=\"Tools\"\u003e\n\u003c/p\u003e\n\n# EQEmu MCP Server\n\n\u003e Give your AI assistant full context on your EverQuest Emulator server — source code, quest API, database schema, documentation, and live game data — so it can write accurate queries, debug issues, and manage content without guessing.\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [EverQuest Emulator](https://docs.eqemu.io/) servers. Works with **Windsurf**, **VS Code**, **Cursor**, **OpenAI Codex**, **Claude Desktop**, and any MCP-compatible AI client.\n\n---\n\n## What's Included\n\nYour AI assistant gets access to **everything** it needs to understand and operate your EQEmu server:\n\n| Data Source | What Your AI Can Access |\n|---|---|\n| **📚 EQEmu Documentation** | Full-text search across all 638 pages of [docs.eqemu.io](https://docs.eqemu.io) — server operation guides, configuration references, quest tutorials, and more |\n| **🗄️ Database Schema Docs** | Detailed documentation for all 261 tables across 48 categories — column names, types, descriptions, and ER relationship diagrams |\n| **🔍 Live Database** | Read-only SQL queries against your actual game database — NPCs, items, spawns, loot, characters, accounts, zones, spells, factions, tasks, tradeskills |\n| **💻 C++ Source Code** | Full-text search across the EQEmu C++ codebase — find how mechanics work, trace calculations, understand game systems |\n| **📜 Quest Scripts** | Browse and search all Perl/Lua quest scripts across every zone — read quest logic, find event handlers, trace quest flows |\n| **🔧 Quest API Reference** | Complete Lua and Perl quest API documentation — method signatures, event lists, and examples for all 30+ method classes |\n| **⚙️ Server Configuration** | Server rules, content flags, expansion settings, eqemu_config.json (with passwords auto-redacted) |\n| **📋 Server Logs** | Recent server logs and crash logs for debugging |\n| **👤 Characters \u0026 Accounts** | Character inspection (stats, AAs, inventory, guild), account details, IP history, alt/multibox detection |\n| **🗺️ Zone Details** | Zone information with spawn counts, NPC lists, doors/portals, ground spawns, forage/fishing tables, patrol grids |\n\n\u003e **No guessing.** Your AI looks up the exact schema, follows the correct relationships, and writes accurate queries on the first try.\n\n---\n\n## Why?\n\nWhen you ask an AI assistant to write a query, inspect spawn data, or debug a quest issue, it has to **guess** table names, column names, relationships, and valid values. It gets things wrong. You end up copy-pasting schema docs and correcting hallucinated SQL.\n\nThis MCP server eliminates that. Your AI assistant can:\n\n- **Look up exact schema** — `get_schema_doc(\"npc_types\")` returns all 80+ columns with types and descriptions\n- **Follow relationships** — `table_relationships(\"spawn2\")` shows FK links through the entire spawn chain\n- **Search documentation** — `search_docs(\"loottable_id\")` finds every doc page referencing that column\n- **Query live data** — `run_query(\"SELECT * FROM npc_types WHERE name LIKE '%Nagafen%'\")` hits your actual database\n- **Inspect full chains** — NPC → faction → loot → spawn group → grid path, all from structured tools\n\nThe result: correct queries on the first try, accurate quest scripts, and faster debugging.\n\n---\n\n## Tools (60+)\n\n### Read-Only (always available)\n\n| Category | Tools | Description |\n|---|---|---|\n| **C++ Source** | `search_source` `get_source_file` `list_source_files` | Search and browse the EQEmu C++ codebase |\n| **Quest API** | `list_quest_api_classes` `get_quest_api_methods` | Browse Lua/Perl quest API method signatures |\n| **Quest Scripts** | `list_quest_zones` `list_quest_files` `read_quest_file` `search_quests` | Browse and search quest scripts across all zones |\n| **Server Files** | `list_server_files` `read_server_file` `get_server_config` | Server files, plugins, config (passwords redacted) |\n| **Server Info** | `get_server_rules` `get_server_logs` `get_crash_logs` `get_content_flags` `get_expansion_info` | Rules, logs, crash analysis, content flags |\n| **Database** | `list_tables` `describe_table` `run_query` `table_relationships` | Schema inspection and read-only SQL |\n| **NPCs** | `search_npcs` `get_npc` | NPC search by name/zone/level with spawn locations |\n| **Items** | `search_items` `get_item` `search_items_by_stat` | Item search by name/type/level or stat thresholds |\n| **Spawns** | `get_zone_spawns` `get_spawngroup` | Spawn points, spawn groups, placeholder/named setups |\n| **Loot** | `get_npc_loot` | Full loot chain: NPC → loottable → lootdrop → items |\n| **Merchants** | `get_merchant_items` | Merchant inventories |\n| **Zones** | `search_zones` `get_zone_info` | Zone lookup with spawn/NPC/door counts |\n| **Spells** | `search_spells` `get_spell` | Spell search and full effect/class breakdown |\n| **Factions** | `search_factions` `get_npc_faction` | Faction search and NPC faction kill-hit details |\n| **Tasks** | `search_tasks` `get_task` | Task search and full activity/reward breakdown |\n| **Characters** | `list_characters` `get_character` `get_online_characters` | Character inspection, stats, AAs, inventory, online players |\n| **Accounts** | `get_account_info` `find_associated_accounts` | Account investigation, IP history, alt detection |\n| **Tradeskills** | `search_recipes` `get_recipe` | Recipe search and component/result breakdown |\n| **Grids** | `get_npc_grid` | NPC patrol paths with waypoint coordinates |\n| **Doors** | `get_zone_doors` | Zone doors/portals with destinations, keys, lockpick |\n| **Ground Spawns** | `get_ground_spawns` | Clickable ground items in a zone |\n| **Forage/Fishing** | `get_zone_forage_fishing` | Zone forage and fishing loot tables |\n| **Documentation** | `search_docs` `read_doc` `list_doc_sections` | Full-text search across docs.eqemu.io |\n| **Schema Docs** | `get_schema_doc` `list_schema_tables` | Table docs with column descriptions and ER relationships |\n| **Quest API Docs** | `get_quest_api_doc` | Official quest API docs with signatures and examples |\n| **Server Docs** | `get_server_doc` | Server operation guides and command references |\n\n### Write Tools (opt-in)\n\nEnable with `EQEMU_ACCESS_MODE=readwrite`:\n\n| Category | Tools | Description |\n|---|---|---|\n| **Quest Editing** | `write_quest_file` `delete_quest_file` | Create, edit, or delete quest scripts |\n| **Server Rules** | `set_server_rule` | Change server rule values |\n| **Content Flags** | `set_content_flag` | Enable/disable content flags |\n| **NPC Management** | `create_npc` `update_npc` | Create or modify NPCs |\n| **Spawn Management** | `create_spawn` `delete_spawn` | Add/remove spawn points |\n| **Loot Management** | `add_loot_to_npc` | Add items to NPC loot tables |\n| **Merchants** | `add_merchant_item` `remove_merchant_item` | Manage merchant inventories |\n| **Data Buckets** | `get_data_buckets` `set_data_bucket` | Read/write data buckets |\n| **Database** | `run_write_query` | Execute INSERT/UPDATE/DELETE queries |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.10+**\n- **Access to an EQEmu server** ([akk-stack](https://github.com/Akkadius/akk-stack) recommended)\n- **ripgrep** (optional — for fast source code search, falls back to grep)\n\n### Option A: Docker (Recommended)\n\n```bash\ngit clone https://github.com/straps-eq/eqemu-mcp-server.git\ncd eqemu-mcp-server\n\ncp .env.example .env\n# Edit .env with your database credentials and paths\n\ndocker compose up -d\n```\n\nThe server starts on port 8888. Connect your AI client to `http://YOUR_SERVER_IP:8888/sse`.\n\n#### akk-stack Integration\n\nIf you're running [akk-stack](https://github.com/Akkadius/akk-stack), the MCP server can join your existing Docker network and talk to MariaDB directly. **No separate `.env` file is needed** — the compose overlay reads credentials from your akk-stack `.env` automatically.\n\n**Step 1: Clone into your akk-stack directory**\n```bash\ncd /opt/akk-stack\ngit clone https://github.com/straps-eq/eqemu-mcp-server.git\n```\n\n**Step 2 (optional): Add token authentication**\n\nTo require a token for connections, add this to your akk-stack `.env`:\n```bash\necho \"EQEMU_MCP_TOKEN=$(openssl rand -hex 32)\" \u003e\u003e /opt/akk-stack/.env\n# View the generated token:\ngrep EQEMU_MCP_TOKEN /opt/akk-stack/.env\n```\n\n**Step 3: Build and start the MCP container**\n```bash\ncd /opt/akk-stack\n\n# Build the image\ndocker compose -f docker-compose.yml \\\n  -f eqemu-mcp-server/docker-compose.akk-stack.yml \\\n  build eqemu-mcp\n\n# Start (only the MCP container — does NOT restart your game server)\ndocker compose -f docker-compose.yml \\\n  -f eqemu-mcp-server/docker-compose.akk-stack.yml \\\n  up -d --no-deps eqemu-mcp\n```\n\n\u003e **⚠️ Important:** Always use `--no-deps eqemu-mcp` to start *only* the MCP container. Without `--no-deps`, Docker Compose may recreate your MariaDB and EQEmu server containers, causing a server restart.\n\n**Step 4: Open the firewall**\n```bash\nsudo ufw allow 8888/tcp\n```\n\n**Step 5: Verify**\n```bash\ndocker logs akk-stack-eqemu-mcp-1 --tail 5\n# Should show: \"Uvicorn running on http://0.0.0.0:8888\"\n```\n\nThe MCP server is **read-only by default**. It automatically:\n- Connects to MariaDB via the `backend` network (no external IP needed)\n- Mounts your `code/` and `server/` directories read-only\n- Uses your existing `MARIADB_PASSWORD` from the akk-stack `.env`\n\n**Configuration:** All settings go in your akk-stack `.env` (`/opt/akk-stack/.env`) — you do **not** create a separate `.env` inside the `eqemu-mcp-server/` folder. Available variables:\n\n| Variable | Default | Description |\n|---|---|---|\n| `MARIADB_PASSWORD` | *(from akk-stack)* | Database password — already in your `.env` |\n| `IP_ADDRESS` | `0.0.0.0` | Bind address — already in your `.env` |\n| `EQEMU_DB_NAME` | `peq` | Database name — set this if your DB isn't named `peq` |\n| `EQEMU_DB_USER` | `eqemu` | Database user — set to a read-only user for extra safety (see [Read-Only DB User](#read-only-database-user-recommended)) |\n| `EQEMU_DB_PASSWORD` | `${MARIADB_PASSWORD}` | Database password — override if using a separate read-only user |\n| `EQEMU_MCP_TOKEN` | *(empty)* | Set to require token auth on connections |\n| `MCP_ACCESS_MODE` | `read` | Set to `readwrite` to enable write tools |\n\n### Option B: Manual Install (No Docker)\n\n```bash\ngit clone https://github.com/straps-eq/eqemu-mcp-server.git\ncd eqemu-mcp-server\n\npython3 -m venv venv\nsource venv/bin/activate\npip install -e .\n\ncp .env.example .env\n# Edit .env with your server paths and database credentials\n\n# Start SSE server\n./start.sh --sse 8888\n```\n\n### Finding Your Database Credentials\n\n**akk-stack users:**\n```bash\ncd /opt/akk-stack \u0026\u0026 make info\n```\n\nOr read `eqemu_config.json`:\n```bash\ncat /opt/akk-stack/server/eqemu_config.json | python3 -m json.tool\n```\n\n\u003e **Note:** If running the MCP server outside Docker (directly on the host), use the host's external IP for `EQEMU_DB_HOST`, not `127.0.0.1` or `mariadb`.\n\n---\n\n## Connecting Your AI Client\n\n### Option 1: SSE (Recommended for Remote)\n\nStart the server:\n```bash\n./start.sh --sse 8888\n```\n\nThen configure your AI client:\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWindsurf\u003c/b\u003e\u003c/summary\u003e\n\nEdit `~/.codeium/windsurf/mcp_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"eqemu\": {\n      \"serverUrl\": \"http://YOUR_SERVER_IP:8888/sse\"\n    }\n  }\n}\n```\n\nWith token authentication enabled:\n```json\n{\n  \"mcpServers\": {\n    \"eqemu\": {\n      \"serverUrl\": \"http://YOUR_SERVER_IP:8888/sse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor\u003c/b\u003e\u003c/summary\u003e\n\nIn Settings → MCP Servers, add:\n```json\n{\n  \"mcpServers\": {\n    \"eqemu\": {\n      \"url\": \"http://YOUR_SERVER_IP:8888/sse\"\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eVS Code (GitHub Copilot)\u003c/b\u003e\u003c/summary\u003e\n\nOpen Command Palette → \"MCP: Open User Configuration\" (or edit `.vscode/mcp.json` in your workspace):\n```json\n{\n  \"servers\": {\n    \"eqemu\": {\n      \"type\": \"sse\",\n      \"url\": \"http://YOUR_SERVER_IP:8888/sse\"\n    }\n  }\n}\n```\n\nWith token authentication:\n```json\n{\n  \"servers\": {\n    \"eqemu\": {\n      \"type\": \"sse\",\n      \"url\": \"http://YOUR_SERVER_IP:8888/sse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOpenAI Codex CLI\u003c/b\u003e\u003c/summary\u003e\n\nRun `codex mcp add` or edit `~/.codex/config.toml`:\n```toml\n[mcp_servers.eqemu]\nurl = \"http://YOUR_SERVER_IP:8888/sse\"\nenabled = true\n\n[mcp_servers.eqemu.env]\nMCP_TOKEN = \"YOUR_TOKEN\"\n```\n\nOr with token via environment variable:\n```toml\n[mcp_servers.eqemu]\nurl = \"http://YOUR_SERVER_IP:8888/sse\"\nbearer_token_env_var = \"MCP_TOKEN\"\nenabled = true\n```\n\nThen set `export MCP_TOKEN=YOUR_TOKEN` in your shell.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Desktop\u003c/b\u003e\u003c/summary\u003e\n\nClaude Desktop doesn't natively support SSE. Use stdio mode instead (Option 2), or use [mcp-proxy](https://github.com/punkpeye/mcp-proxy) to bridge SSE to stdio.\n\u003c/details\u003e\n\n### Option 2: stdio (Local)\n\nIf the MCP server is on the same machine as your AI client:\n\n```json\n{\n  \"mcpServers\": {\n    \"eqemu\": {\n      \"command\": \"/path/to/venv/bin/python\",\n      \"args\": [\"/path/to/eqemu-mcp-server/server.py\"],\n      \"env\": {\n        \"EQEMU_SOURCE_PATH\": \"/opt/akk-stack/code\",\n        \"EQEMU_QUESTS_PATH\": \"/opt/akk-stack/server/quests\",\n        \"EQEMU_SERVER_PATH\": \"/opt/akk-stack/server\",\n        \"EQEMU_DB_HOST\": \"YOUR_SERVER_IP\",\n        \"EQEMU_DB_PORT\": \"3306\",\n        \"EQEMU_DB_USER\": \"eqemu\",\n        \"EQEMU_DB_PASSWORD\": \"YOUR_DB_PASSWORD\",\n        \"EQEMU_DB_NAME\": \"peq\",\n        \"RG_PATH\": \"/path/to/rg\",\n        \"EQEMU_ACCESS_MODE\": \"read\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## Permission Model\n\n| Mode | `EQEMU_ACCESS_MODE` | Tools | Use Case |\n|---|---|---|---|\n| **Read-Only** | `read` (default) | 50+ read-only | Safe for sharing — SQL restricted to SELECT, passwords redacted |\n| **Read-Write** | `readwrite` | All 60+ | Server admins actively managing content |\n\n```bash\n# In .env\nEQEMU_ACCESS_MODE=read      # safe default\nEQEMU_ACCESS_MODE=readwrite  # full access\n```\n\n---\n\n## Security\n\nBy default, the MCP server accepts connections from anyone who can reach the port. Use one or both of these methods to restrict access.\n\n### Option 1: Firewall (IP Restriction)\n\nUse UFW to only allow specific IP addresses to connect:\n\n```bash\n# Remove any existing open rule\nsudo ufw delete allow 8888/tcp\n\n# Allow only your IP\nsudo ufw allow from YOUR_HOME_IP to any port 8888 proto tcp\n\n# Allow additional users\nsudo ufw allow from FRIEND_IP to any port 8888 proto tcp\n\n# Verify\nsudo ufw status | grep 8888\n```\n\nThis is the simplest approach — no code changes needed. To find your IP, visit https://whatismyip.com.\n\n### Option 2: Token Authentication\n\nRequire a secret token for all SSE connections. Set `EQEMU_MCP_TOKEN` in your `.env`:\n\n```bash\n# Generate a random token\nEQEMU_MCP_TOKEN=$(openssl rand -hex 32)\necho \"EQEMU_MCP_TOKEN=$EQEMU_MCP_TOKEN\" \u003e\u003e .env\necho \"Your token: $EQEMU_MCP_TOKEN\"\n```\n\nThen restart the server. Clients must include the token in the URL:\n\n**Windsurf:**\n```json\n{\n  \"mcpServers\": {\n    \"eqemu\": {\n      \"serverUrl\": \"http://YOUR_SERVER_IP:8888/sse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_TOKEN\"\n      }\n    }\n  }\n}\n```\n\nThe token can also be passed as a query parameter (`?token=YOUR_TOKEN`) for clients that don't support custom headers. Without a valid token, the server returns `401 Unauthorized`.\n\n### Option 3: Read-Only Database User (Recommended)\n\nBy default, the MCP server connects to MariaDB using the `eqemu` user, which has full read/write access. For production or shared deployments, create a dedicated read-only MySQL user so that **no database writes are possible**, even if a bug or prompt injection bypasses the application-level SQL validation.\n\n**Step 1: Create the read-only user**\n\n```bash\n# For akk-stack (Docker):\ndocker exec -it akk-stack-mariadb-1 mysql -u root -p${MARIADB_PASSWORD} -e \"\n  CREATE USER 'eqemu_readonly'@'%' IDENTIFIED BY 'PICK_A_STRONG_PASSWORD';\n  GRANT SELECT, SHOW DATABASES, SHOW VIEW ON \\`YOUR_DB_NAME\\`.* TO 'eqemu_readonly'@'%';\n  FLUSH PRIVILEGES;\n\"\n```\n\nReplace `YOUR_DB_NAME` with your database name (e.g. `peq`, `e9profusion_production`) and `PICK_A_STRONG_PASSWORD` with a password of your choice.\n\n**Step 2: Add to your `.env`**\n\n```env\nEQEMU_DB_USER=eqemu_readonly\nEQEMU_DB_PASSWORD=PICK_A_STRONG_PASSWORD\n```\n\n**Step 3: Restart the MCP container**\n\n```bash\ncd /opt/akk-stack\ndocker compose -f docker-compose.yml \\\n  -f eqemu-mcp-server/docker-compose.akk-stack.yml \\\n  up -d --no-deps --force-recreate eqemu-mcp\n```\n\nThe MCP server now connects with SELECT-only permissions. Any write attempt — whether from the application, an AI, or a crafted query — will be rejected by MySQL itself.\n\n### Combining All Three\n\nFor maximum security, use all three layers:\n1. **Firewall** — restricts which IPs can connect\n2. **Token auth** — ensures only authorized clients can use the tools\n3. **Read-only DB user** — guarantees no database writes at the MySQL level, regardless of application behavior\n\n---\n\n## Example Conversations\n\nOnce connected, your AI assistant can handle requests like:\n\n**Querying \u0026 Inspecting:**\n\u003e \"Write me a query to find all NPCs in crushbone that drop cloth items\"\n\u003e\n\u003e \"What's in Lord Nagafen's loot table?\"\n\u003e\n\u003e \"Show me all items with haste \u003e= 30\"\n\u003e\n\u003e \"Who's online right now?\"\n\n**Debugging \u0026 Investigation:**\n\u003e \"Find all accounts that share IPs with the character Soandso\"\n\u003e\n\u003e \"Show me the patrol path for the guard NPCs in Qeynos\"\n\u003e\n\u003e \"What faction hits do you get for killing a Freeport Militia member?\"\n\u003e\n\u003e \"Show me the most recent crash logs\"\n\n**Quest Development:**\n\u003e \"What Lua quest methods are available on the Client object?\"\n\u003e\n\u003e \"Search the source for how spell resistance is calculated\"\n\u003e\n\u003e \"Find all quest scripts that use `eq.spawn2`\"\n\n**Content Management** (write mode):\n\u003e \"Create a new NPC named Test_Merchant at level 30\"\n\u003e\n\u003e \"Add a Cloth Cap to merchant 123's inventory\"\n\u003e\n\u003e \"Set the AA:ExpPerPoint rule to 50000000\"\n\n---\n\n## Deployment on akk-stack\n\n```bash\ncd /opt/akk-stack\n\n# Create venv\npython3 -m venv eqemu-mcp-venv\nsource eqemu-mcp-venv/bin/activate\npip install mcp[cli] mysql-connector-python\n\n# Install ripgrep (optional but recommended)\napt-get install -y ripgrep\n\n# Clone documentation (for docs tools)\ngit clone --depth 1 https://github.com/EQEmu/eqemu-docs-v2.git eqemu-docs\n\n# Clone and configure\ngit clone https://github.com/straps-eq/eqemu-mcp-server.git\ncd eqemu-mcp-server\ncp .env.example .env\n# Edit .env with: DB host/password (from `make info`), paths, access mode\n\n# Test\npython server.py  # Ctrl+C to stop\n\n# Run SSE\n./start.sh --sse 8888\n\n# Open the firewall port\nsudo ufw allow 8888/tcp\n```\n\n### Running as a systemd Service\n\n```bash\nsudo tee /etc/systemd/system/eqemu-mcp.service \u003e /dev/null \u003c\u003c 'EOF'\n[Unit]\nDescription=EQEmu MCP Server\nAfter=docker.service\n\n[Service]\nType=simple\nWorkingDirectory=/opt/akk-stack/eqemu-mcp-server\nExecStart=/opt/akk-stack/eqemu-mcp-server/start.sh --sse 8888\nRestart=always\nUser=root\n\n[Install]\nWantedBy=multi-user.target\nEOF\n\nsudo systemctl enable eqemu-mcp\nsudo systemctl start eqemu-mcp\n```\n\n---\n\n## Architecture\n\n```\neqemu-mcp-server/\n  server.py                          # Entry point — registers tools based on access mode\n  start.sh                           # Startup script (loads .env, activates venv)\n  Dockerfile                         # Docker image for containerized deployment\n  docker-compose.yml                 # Standalone Docker Compose\n  docker-compose.akk-stack.yml       # akk-stack integration overlay\n  eqemu_mcp/\n    config.py                        # Centralized configuration from env vars\n    helpers.py                       # Shared utilities (DB connections, ripgrep, file I/O)\n    tools_source.py                  # C++ source code search and browsing\n    tools_quest_api.py               # Lua/Perl quest API method parsing\n    tools_quests.py                  # Quest script browsing + editing (write)\n    tools_server.py                  # Server config, rules, logs, content flags\n    tools_database.py                # Schema inspection and SQL queries\n    tools_entities.py                # NPC, item, spawn, loot, zone, spell lookups\n    tools_entities_write.py          # NPC, spawn, loot, merchant write operations\n    tools_docs.py                    # EQEmu documentation search (docs.eqemu.io)\n    tools_lookup.py                  # Characters, accounts, recipes, doors, grids, factions\n```\n\n---\n\n## Self-Hosting for Other Server Operators\n\nEach EQEmu server operator runs their own instance:\n\n1. Clone this repo on the server\n2. Configure `.env` with their paths and DB credentials\n3. Set `EQEMU_ACCESS_MODE=read` (safe default)\n4. Run via stdio or SSE\n5. Connect their AI client\n\nThe server is completely self-contained — no external services, no cloud dependencies, no API keys. All data stays on your machine.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstraps-eq%2Feqemu-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstraps-eq%2Feqemu-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstraps-eq%2Feqemu-mcp-server/lists"}