{"id":30838976,"url":"https://github.com/unclemusclez/eveonlinemcp","last_synced_at":"2025-09-06T18:14:24.518Z","repository":{"id":313347172,"uuid":"1051069894","full_name":"unclemusclez/EveOnlineMCP","owner":"unclemusclez","description":" A local MCP server for accessing the EVE Online ESI API","archived":false,"fork":false,"pushed_at":"2025-09-05T13:22:19.000Z","size":22,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-05T13:35:59.542Z","etag":null,"topics":["esi","eve","eveonline","fastapi","fastmcp","mcp","oauth","openapi"],"latest_commit_sha":null,"homepage":"https://discord.waterpistol.co","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unclemusclez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2025-09-05T11:51:50.000Z","updated_at":"2025-09-05T13:22:23.000Z","dependencies_parsed_at":"2025-09-05T13:36:01.558Z","dependency_job_id":"a8d5c945-1395-4baa-956d-ab854d4a3e5f","html_url":"https://github.com/unclemusclez/EveOnlineMCP","commit_stats":null,"previous_names":["unclemusclez/eveonlinemcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/unclemusclez/EveOnlineMCP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unclemusclez%2FEveOnlineMCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unclemusclez%2FEveOnlineMCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unclemusclez%2FEveOnlineMCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unclemusclez%2FEveOnlineMCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unclemusclez","download_url":"https://codeload.github.com/unclemusclez/EveOnlineMCP/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unclemusclez%2FEveOnlineMCP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273941614,"owners_count":25195132,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"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":["esi","eve","eveonline","fastapi","fastmcp","mcp","oauth","openapi"],"created_at":"2025-09-06T18:14:17.588Z","updated_at":"2025-09-06T18:14:24.501Z","avatar_url":"https://github.com/unclemusclez.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Eve Online ESI MCP Server\r\n\r\n## Overview\r\n\r\nThis project implements a local MCP (Model Context Protocol) server for accessing the EVE Online ESI (EVE Swagger Interface) API. It uses the FastMCP library to create a proxy server based on the ESI OpenAPI specification, with built-in support for OAuth authentication via EVE Online's SSO. The server handles multiple characters, stores authentication tokens securely in a SQLite database, and automatically refreshes expired tokens. It's designed for developers and EVE Online enthusiasts who need programmatic access to ESI endpoints in a secure, multi-character setup.\r\n\r\nKey technologies:\r\n- Python 3.8+\r\n- FastMCP for MCP server creation\r\n- httpx for asynchronous HTTP requests\r\n- SQLite for local token storage\r\n- OAuth2 PKCE flow for secure authentication\r\n\r\n## Features\r\n\r\n- **Multi-Character Support**: Authenticate and manage multiple EVE Online characters, with tokens stored per character.\r\n- **Automatic Token Refresh**: Tokens are refreshed on-demand when expired, using stored refresh tokens.\r\n- **Dynamic Authorization**: Automatically adds Bearer tokens to ESI requests based on the character ID in the API path.\r\n- **SSO Integration**: Easy character addition via browser-based OAuth flow.\r\n- **OpenAPI-Driven**: Generated from the official ESI OpenAPI spec, ensuring compatibility with future API changes.\r\n- **Logging**: Detailed debug logging to a file for troubleshooting.\r\n- **Local Storage**: Tokens and character data stored in `~/.esi-mcp/characters.db`.\r\n\r\n## Installation\r\n\r\n1. **Prerequisites**:\r\n   - Python 3.8 or higher.\r\n   - Install required dependencies:\r\n     ```\r\n     pip install fastmcp httpx sqlite3 asyncio secrets base64 hashlib re logging pathlib urllib3\r\n     ```\r\n     Note: Some dependencies like `fastmcp` may require specific installation instructions; check the [FastMCP documentation](https://fastmcp.cloud/docs) for details.\r\n\r\n2. **Clone the Repository**:\r\n   ```\r\n   git clone https://github.com/unclemusclez/EveOnlineMCP.git\r\n   cd EveOnlineMCP\r\n   ```\r\n\r\n3. **Run the Script**:\r\n   ```\r\n   python esi.py\r\n   ```\r\n   This starts the MCP server in stdio transport mode. For other transports (e.g., HTTP), modify `mcp.run(transport=\"stdio\")` accordingly.\r\n\r\n## Usage\r\n\r\n### Adding a Character\r\nThe server includes a tool `add_character` to authenticate new characters:\r\n- Call the tool via the MCP interface (e.g., from a client).\r\n- It opens a browser for EVE Online SSO login.\r\n- After authentication, the character's details and tokens are saved to the database.\r\n\r\nExample (pseudocode for client-side call):\r\n```python\r\nresult = await mcp_client.add_character()\r\nprint(result)  # \"Authenticated character: CharacterName (ID: 123456789)\"\r\n```\r\n### Removing a Character\r\nThe server includes a tool `delete_character` to remove a character from the database:\r\n- Call the tool via the MCP interface (e.g., from a client).\r\n- It removes the character's details and tokens from the database.\r\n- If the character is set as default, this setting is cleared.\r\n\r\nExample (pseudocode for client-side call):\r\n```python\r\nresult = await mcp_client.remove_character(character_id=123456789)\r\nprint(result)  # \"Removed character: CharacterName (ID: 123456789)\"\r\n```\r\n\r\n### Making ESI Requests\r\n- The server proxies ESI endpoints, e.g., `/characters/{character_id}/wallet/`.\r\n- Authentication is handled automatically based on the `character_id` in the path.\r\n- Use a FastMCP client to interact with the server.\r\n\r\nExample client usage:\r\n```python\r\nfrom fastmcp import Client\r\n\r\nasync with Client(\"stdio\") as client:  # Or HTTP transport\r\n    balance = await client.GetCharactersCharacterIdWallet(character_id=123456789)\r\n    print(balance)\r\n```\r\n\r\n### Database Management\r\n- Characters and tokens are stored in `~/.esi-mcp/characters.db`.\r\n- Tables:\r\n  - `characters`: Stores character_id, name, scopes, access_token, refresh_token, token_expiry.\r\n  - `settings`: Stores defaults like `default_character_id`.\r\n\r\nYou can query the DB manually with SQLite tools for inspection.\r\n\r\n### Logging\r\n- Logs are written to `~/.esi-mcp/esi-mcp.log`.\r\n- Set logging level in code if needed (default: DEBUG).\r\n\r\n## Configuration\r\n\r\n- **OAuth Constants**:\r\n  - `CLIENT_ID` and `CLIENT_SECRET`: Replace with your EVE Online developer app credentials.\r\n  - `SCOPES`: List of ESI scopes; customize as needed.\r\n  - `CALLBACK_URL`: Local callback for SSO (default: http://localhost:8000/auth/callback).\r\n\r\n- **Compatibility Date**: Set to \"2025-08-26\" for future-proofing; update as per ESI changes.\r\n\r\n- **Database Path**: Customizable via `DB_PATH`.\r\n\r\n## Troubleshooting\r\n\r\n- **Token Errors**: Check logs for refresh failures; ensure CLIENT_ID is valid.\r\n- **SSO Issues**: Verify browser opens and callback port (8000) is free.\r\n- **Unauthorized (401)**: Ensure character is added and has required scopes (e.g., `esi-wallet.read_character_wallet.v1`).\r\n- **No Tokens Found**: Run `add_character` tool first.\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please fork the repo and submit pull requests for bug fixes or features. Ensure code follows PEP8 and includes tests where possible.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License. See [LICENSE](LICENSE.md) for details.\r\n\r\n---\r\n\r\nFor more details on EVE Online ESI, visit the [official documentation](https://developers.eveonline.com/api-explorer). For FastMCP, refer to [FastMCP Docs](https://fastmcp.cloud/docs).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funclemusclez%2Feveonlinemcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funclemusclez%2Feveonlinemcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funclemusclez%2Feveonlinemcp/lists"}