convez.ai
MCP ServerIntegração & APIsAvançado
samadehxc121443-cloud

ClaudeMcpServer

samadehxc121443-cloud/ClaudeMcpServer

MCP server .NET 10 com autenticação por token para Claude Desktop

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP production-ready em C# .NET 10 que conecta Claude Desktop a ferramentas locais e iCloud Mail via JSON-RPC 2.0. Implementa sistema robusto de licenciamento por token com validação por hora e controle de acesso granular.

Instalação

$npx convez-ai samadehxc121443-cloud/ClaudeMcpServer

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
—
Issues abertas
11
Contribuidores
2

Casos de uso

  • Integrar Claude Desktop com serviços de email e ferramentas locais
  • Implementar controle de acesso por API key com expiração configurável
  • Estender capacidades do Claude com tools customizadas via DI

Veredito

Solução técnica sólida e production-ready para estender Claude Desktop com ferramentas locais. Arquitetura em camadas bem definida (Domain/Application/Infrastructure) facilita manutenção; sistema de licenciamento por token é robusto e apropriado para deployments empresariais.

README

A tradução para o português deste README ainda está na fila.

ClaudeMcpServer

.NET 10 License: MIT Build

A production-ready Model Context Protocol (MCP) server written in C# .NET 10.
Connects Claude Desktop on Windows and macOS to a set of local tools via the MCP stdio transport, with a cloud-hosted license server for per-client access control.


Architecture

┌────────────────────────────────────────────────────────────────────┐
│                        ClaudeMcpServer.Host                         │
│  (stdio binary — runs locally on the client machine)                │
│                                                                      │
│  ┌──────────┐  ┌─────────────────┐  ┌──────────────────────────┐   │
│  │  Domain  │◄─│  Application    │◄─│      Infrastructure      │   │
│  │          │  │                 │  │                          │   │
│  │Interfaces│  │  McpService     │  │  StdioTransport          │   │
│  │Entities  │  │  Handlers:      │  │  ToolRegistry            │   │
│  │ValueObjs │  │  - Initialize   │  │  Tools (see below)       │   │
│  │          │  │  - ListTools    │  │  LicenseService          │   │
│  └──────────┘  │  - CallTool ────┼──┤   (token cache, 1h TTL) │   │
│                │  - Ping         │  └──────────────────────────┘   │
│                └─────────────────┘                                   │
└───────────────────────────┬────────────────────────────────────────┘
                            │ stdio (JSON-RPC 2.0)
                            ▼
                      Claude Desktop

                            │ HTTPS (token exchange, once per hour)
                            ▼
┌────────────────────────────────────────────────────────────────────┐
│                    ClaudeMcpServer.LicenseServer                    │
│  (ASP.NET Core Minimal API — deployed on Railway)                   │
│                                                                      │
│  POST /api/auth/token      — exchange API key for session token      │
│  POST /api/license/validate — validate API key directly             │
│  GET  /health              — DB connectivity check                   │
│  POST /api/admin/keys      — create license key (admin)             │
│  GET  /api/admin/keys      — list all keys (admin)                  │
│  DELETE /api/admin/keys/:id — revoke key (admin)                    │
└────────────────────────────────────────────────────────────────────┘

Dependency rule: Domain ← Application ← Infrastructure ← Host.
Extension point: Adding a new tool requires exactly one class and one DI registration — no changes to the protocol layer.


License System

Each client installation has an API key stored in appsettings.json. On startup and every hour, LicenseService exchanges the API key for a short-lived session token issued by the license server. Tool calls validate the token from memory (no network round-trip per call).

FeatureDescription
Token rotating authAPI key exchanges for a 1-hour session token, cached in memory
Per-request enforcementCallToolHandler validates the cached token on every tools/call
Subscription expiryKeys can have a PlanName and ExpiresAt date — expired keys are rejected
Admin-protected endpointsPOST/GET/DELETE /api/admin/keys require X-Admin-Key header
Health checkGET /health returns DB status and key count — used by Railway

Built-in Tools

System Tools

ToolDescription
get_system_infoOS, CPU architecture, .NET version, hostname, working set
get_datetimeCurrent date/time in multiple formats with optional IANA timezone
read_fileRead text/code files up to 1 MB (whitelisted extensions)
list_directoryList directory contents with type, size, and modification date

Email Tools (iCloud / me.com)

ToolDescription
list_emailsList recent emails from the iCloud inbox (sender, subject, date, preview)
read_emailRead the full content of an email by its unique ID
search_emailsSearch inbox by subject, sender, body text, or all fields
send_emailSend an email with optional HTML body and file attachments
get_email_attachmentsExtract attachments from a specific email

Setup: Email tools require an app-specific password generated at appleid.apple.com. Set it in appsettings.json under Email.Password. Never commit real credentials.


Quick Start

Prerequisites

1. Clone and build

git clone https://github.com/samadehxc121443-cloud/ClaudeMcpServer.git
cd ClaudeMcpServer
dotnet build ClaudeMcpServer.sln

2. Run tests

dotnet test ClaudeMcpServer.sln

3. Publish a self-contained binary

# Windows x64
dotnet publish src/ClaudeMcpServer.Host/ -c Release -r win-x64 --self-contained -o ./publish/win-x64

# macOS Apple Silicon (M1/M2/M3)
dotnet publish src/ClaudeMcpServer.Host/ -c Release -r osx-arm64 --self-contained -o ./publish/osx-arm64

4. Configure Claude Desktop

Windows — edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "claude-mcp-server": {
      "command": "C:\\publish\\win-x64\\ClaudeMcpServer.Host.exe",
      "args": [],
      "env": {}
    }
  }
}

macOS — edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "claude-mcp-server": {
      "command": "/absolute/path/to/publish/osx-arm64/ClaudeMcpServer.Host",
      "args": [],
      "env": {}
    }
  }
}

Restart Claude Desktop. The tools will appear in Claude's tool panel.


Adding a New Tool

Step 1 — Create src/ClaudeMcpServer.Infrastructure/Tools/MyTool.cs:

using System.Text.Json;
using System.Text.Json.Nodes;
using ClaudeMcpServer.Domain.Entities;
using ClaudeMcpServer.Domain.Interfaces;
using ClaudeMcpServer.Domain.ValueObjects;

public sealed class MyTool : IToolHandler
{
    public string ToolName => "my_tool";

    public ToolDefinition GetDefinition() => new(
        ToolName,
        "Does something useful.",
        new JsonObject { ["type"] = "object", ["properties"] = new JsonObject() });

    public Task<ToolResult> ExecuteAsync(JsonElement parameters, CancellationToken ct)
        => Task.FromResult(ToolResult.Success("Hello from MyTool!"));
}

Step 2 — Register in src/ClaudeMcpServer.Host/Program.cs:

services.AddSingleton<IToolHandler, MyTool>();

Done. Rebuild and restart Claude Desktop.


Project Structure

ClaudeMcpServer/
├── src/
│   ├── ClaudeMcpServer.Domain/           # Interfaces, entities, value objects
│   ├── ClaudeMcpServer.Application/      # Handlers, McpService, DTOs
│   ├── ClaudeMcpServer.Infrastructure/   # Tools, transport, registry, LicenseService
│   ├── ClaudeMcpServer.Host/             # Entry point, DI wiring, appsettings
│   └── ClaudeMcpServer.LicenseServer/    # Standalone license API (Railway)
│       ├── Data/                         # EF Core DbContext
│       ├── DTOs/                         # Request/response models
│       ├── Filters/                      # AdminKeyFilter (endpoint security)
│       ├── Migrations/                   # EF Core database migrations
│       ├── Models/                       # LicenseKey, SessionToken entities
│       ├── Repositories/                 # IRepository<T>, Repository interfaces + UnitOfWork
│       ├── Services/                     # ILicenseManagerService, LicenseManagerService, LoggingLicenseManagerService
│       ├── Dockerfile                    # Container build for Railway
│       └── Program.cs                    # Minimal API endpoints
├── tests/
│   ├── ClaudeMcpServer.Domain.Tests/
│   ├── ClaudeMcpServer.Application.Tests/
│   └── ClaudeMcpServer.Infrastructure.Tests/
├── railway.json                          # Railway deployment config
└── ClaudeMcpServer.sln

License Server — Required Environment Variables (Railway)

VariableDescription
AdminKeySecret key for admin endpoints (X-Admin-Key header)
PORTHTTP port (Railway sets this automatically)
ConnectionStrings__DefaultConnectionSQLite path, e.g. Data Source=/app/data/licenses.db

License

MIT

Ver o original no GitHub

Bom para

Relacionados