{"id":30232152,"url":"https://github.com/barandev/mcp-server-template","last_synced_at":"2026-04-15T07:38:19.069Z","repository":{"id":308621392,"uuid":"1033476414","full_name":"BaranDev/mcp-server-template","owner":"BaranDev","description":"A production-ready template for building Model Context Protocol (MCP) servers with Python. Includes HTTP client patterns, error handling, connection pooling, and clean separation of concerns. Perfect starting point for integrating any REST API with Claude and other MCP-compatible AI tools.","archived":false,"fork":false,"pushed_at":"2025-08-06T22:01:10.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-14T23:19:10.385Z","etag":null,"topics":["ai-integration","ai-tools","anthropic","api-client","async-python","asyncio","claude","http-client","httpx","mcp","mcp-server","model-context-protocol","production-ready","python","python-template","rest-api","server-template","template"],"latest_commit_sha":null,"homepage":"","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/BaranDev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2025-08-06T21:55:26.000Z","updated_at":"2025-08-06T22:01:13.000Z","dependencies_parsed_at":"2025-08-07T00:07:26.758Z","dependency_job_id":"62e8fa06-1f1d-492e-8aa2-7482af0c0e59","html_url":"https://github.com/BaranDev/mcp-server-template","commit_stats":null,"previous_names":["barandev/mcp-server-template"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/BaranDev/mcp-server-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaranDev%2Fmcp-server-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaranDev%2Fmcp-server-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaranDev%2Fmcp-server-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaranDev%2Fmcp-server-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BaranDev","download_url":"https://codeload.github.com/BaranDev/mcp-server-template/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaranDev%2Fmcp-server-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31831849,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T07:17:56.427Z","status":"ssl_error","status_checked_at":"2026-04-15T07:17:30.007Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-integration","ai-tools","anthropic","api-client","async-python","asyncio","claude","http-client","httpx","mcp","mcp-server","model-context-protocol","production-ready","python","python-template","rest-api","server-template","template"],"created_at":"2025-08-14T23:11:08.181Z","updated_at":"2026-04-15T07:38:19.051Z","avatar_url":"https://github.com/BaranDev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Server Template\n\nA production-ready template for building Model Context Protocol servers with Python. If you want to connect an API or data source to Claude Desktop, this template gives you the basic structure to get started.\n\n## What you get\n\nThis template includes:\n\n- **Four example MCP tools** that you can replace with your own:\n  - Search for things\n  - Get details about a specific item\n  - List categories \n  - Get popular or trending items\n\n- **Clean architecture** split into three files:\n  - `main.py` - your MCP tools and server setup\n  - `api_service.py` - HTTP client with connection pooling, error handling, and retries\n  - `config.py` - settings and environment variable management\n\n- **Production patterns** - proper async/await, resource cleanup, and error handling\n\n## Quick Start\n\n### 1. Set up your environment\n\n```bash\n# Install the required packages\npip install -r requirements.txt\n\n# Copy the example environment file\ncp .env.example .env\n# Edit .env and add your API key and settings\n```\n\n### 2. Customize for your API\n\nOpen `api_service.py` and update:\n- The API URL (currently `https://api.example.com/v1`)\n- Authentication method (currently using API key in params)\n- The endpoint paths to match your API\n\n```python\n# Update the base URL and authentication\nself.base_url = settings.api_base_url  # Change in config.py\nself.api_key = settings.api_key        # Set via environment variable\n\n# Replace the example endpoints\nasync def search(self, query: str, limit: int = 10):\n    return await self._make_request(\"GET\", \"/your-search-endpoint\", ...)\n```\n\n### 3. Update your MCP tools\n\nEdit `main.py` to replace the example tools with your domain-specific functionality:\n\n```python\n@mcp.tool\nasync def your_tool_name(param: str) -\u003e Dict[str, Any]:\n    \"\"\"\n    Describe what your tool does.\n    \n    Args:\n        param: Explain your parameters\n        \n    Returns:\n        Explain what you return\n    \"\"\"\n    client = await get_api_client()\n    result = await client.your_api_method(param)\n    \n    # Transform the API response into the format Claude needs\n    return {\"your\": \"data\"}\n```\n\n### 4. Test your server\n\n```bash\npython main.py\n```\n\n### 5. Connect to Claude Desktop\n\nAdd this to your `claude_desktop_config.json` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"your-server\": {\n      \"command\": \"python\",\n      \"args\": [\"/absolute/path/to/your-server/main.py\"],\n      \"cwd\": \"/absolute/path/to/your-server\",\n      \"env\": {\n        \"API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n## Advanced Configuration\n\n### Adding custom settings\n\nEdit `config.py` to add any settings your API needs:\n\n```python\n@property\ndef your_setting(self) -\u003e str:\n    \"\"\"Description of what this setting controls.\"\"\"\n    return os.getenv(\"YOUR_SETTING\", \"default_value\")\n```\n\n### Environment variables\n\nAll sensitive data should go in your `.env` file:\n\n```bash\nAPI_KEY=your_actual_api_key\nAPI_BASE_URL=https://your-api.com/v1\n# Add other settings as needed\n```\n\n## Learning More\n\n### MCP Resources\n\n- **[MCP Documentation](https://modelcontextprotocol.io/docs)** - Official docs and concepts\n- **[FastMCP GitHub](https://github.com/jlowin/fastmcp)** - The framework this template uses\n- **[Claude Desktop MCP Guide](https://docs.anthropic.com/en/docs/build-with-claude/mcp)** - How to connect your server to Claude\n- **[MCP Examples](https://github.com/modelcontextprotocol/servers)** - Real MCP servers you can study\n\n### Common Questions\n\n**What is MCP?** Model Context Protocol lets you add custom tools to Claude Desktop. Instead of Claude only knowing what it was trained on, you can give it access to live data from APIs, databases, or files.\n\n**What can I build?** Anything that involves getting data for Claude to use. Search your company docs, check recent emails, get weather data, look up product info, etc.\n\n**Do I need to know a lot about APIs?** Basic knowledge helps, but this template handles the hard parts. You mainly need to know what data you want and where to get it.\n\n## License\n\nThis template is released under the MIT License. See [LICENSE](LICENSE) for details.\n\n**Note:** When using this template, make sure to update the LICENSE file with your own name or organization before publishing your MCP server.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarandev%2Fmcp-server-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbarandev%2Fmcp-server-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarandev%2Fmcp-server-template/lists"}