Local MCP Server

English | Tiếng Việt

MCP server tự host, tích hợp Figma, Jira và Google Chat cho các AI agent.

Yêu cầu

• Node.js 20+ (LTS)
• npm 10+

Cài đặt & chạy

npm install -g @manhq/localmcp
localmcp init     # tạo ~/localmcp/settings.json
localmcp config   # điền credentials
localmcp          # khởi động server

Hoặc clone về và chạy local:

npm install
npm run build
npm link          # đăng ký lệnh `localmcp` global
localmcp

Settings mặc định nằm ở: ~/localmcp/settings.json

Biến môi trường được ưu tiên hơn settings file:

PORT=47002 localmcp

Các lệnh

localmcp                         # Chạy MCP server (HTTP)
localmcp stdio                   # Chạy dưới dạng stdio MCP server (tất cả services)
localmcp stdio <service>         # Chạy stdio cho một service cụ thể
localmcp init                    # Tạo settings lần đầu
localmcp list                    # Liệt kê services và biến còn thiếu
localmcp config                  # Mở settings bằng vim hoặc $EDITOR
localmcp config figma            # Config riêng service Figma bằng prompt inline
localmcp config figma token=figd_xxx
localmcp register                # Chọn AI agent, sau đó chọn localmcp hoặc service
localmcp register codex --service figma
localmcp inspect                 # Mở MCP Inspector (HTTP, cần server đang chạy)
localmcp inspect --stdio         # Mở MCP Inspector dùng stdio transport
localmcp playground              # Mở REST API playground trên trình duyệt
localmcp --version               # Xem phiên bản

Endpoints

Khi server đang chạy (localmcp):

| Transport | URL | |-----------|-----| | Streamable HTTP (tất cả) | http://localhost:47001/mcp | | Streamable HTTP (theo service) | http://localhost:47001/mcp/<service> | | Legacy SSE (tất cả) | http://localhost:47001/sse | | Legacy SSE (theo service) | http://localhost:47001/sse/<service> | | REST API | http://localhost:47001/api | | REST Playground | http://localhost:47001/playground | | Health check | http://localhost:47001/health |

Đăng ký với AI Agents

Tip: Chạy localmcp register để đăng ký tự động, hoặc copy lệnh stdio từ log khi khởi động localmcp.

Mỗi agent hỗ trợ hai chế độ transport — chọn cái phù hợp với setup của bạn:

• HTTP — cần server đang chạy (localmcp). Nhanh hơn, dùng chung giữa các agent.
• stdio — agent tự spawn process khi cần. Không cần server chạy sẵn, nhưng mỗi agent dùng process riêng.

Claude Code

HTTP — .claude/settings.local.json

{
  "mcpServers": {
    "localmcp": {
      "type": "http",
      "url": "http://localhost:47001/mcp"
    }
  }
}

stdio — .claude/settings.local.json

{
  "mcpServers": {
    "localmcp": {
      "type": "stdio",
      "command": "localmcp",
      "args": ["stdio"]
    }
  }
}

Hoặc đăng ký bằng command line:

# HTTP
claude mcp add --transport http localmcp http://localhost:47001/mcp

# stdio
claude mcp add localmcp localmcp stdio

Codex

HTTP — ~/.codex/config.toml

[mcp_servers.localmcp]
url = "http://localhost:47001/mcp"

stdio — ~/.codex/config.toml

[mcp_servers.localmcp]
command = "localmcp"
args = ["stdio"]

Hoặc đăng ký bằng command line:

# HTTP
codex mcp add localmcp --url http://localhost:47001/mcp

# stdio
codex mcp add localmcp localmcp stdio

GitHub Copilot / VS Code

HTTP — .vscode/mcp.json

{
  "servers": {
    "localmcp": {
      "type": "http",
      "url": "http://localhost:47001/mcp"
    }
  }
}

stdio — .vscode/mcp.json

{
  "servers": {
    "localmcp": {
      "type": "stdio",
      "command": "localmcp",
      "args": ["stdio"]
    }
  }
}

Cursor

HTTP — .cursor/mcp.json

{
  "mcpServers": {
    "localmcp": {
      "url": "http://localhost:47001/mcp"
    }
  }
}

stdio — .cursor/mcp.json

{
  "mcpServers": {
    "localmcp": {
      "command": "localmcp",
      "args": ["stdio"]
    }
  }
}

Windsurf

HTTP — ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "localmcp": {
      "serverUrl": "http://localhost:47001/mcp"
    }
  }
}

stdio — ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "localmcp": {
      "command": "localmcp",
      "args": ["stdio"]
    }
  }
}

Antigravity

HTTP — ~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "localmcp": {
      "serverUrl": "http://localhost:47001/mcp"
    }
  }
}

stdio — ~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "localmcp": {
      "command": "localmcp",
      "args": ["stdio"]
    }
  }
}

REST API

REST API cho phép gọi bất kỳ tool nào qua HTTP thông thường — tiện cho script, automation và playground.

# Liệt kê services
GET http://localhost:47001/api

# Liệt kê tools của một service
GET http://localhost:47001/api/figma
GET http://localhost:47001/api/atlassian

# Gọi một tool
POST http://localhost:47001/api/figma/whoami
POST http://localhost:47001/api/atlassian/getJiraIssue
Content-Type: application/json

{"issueIdOrKey": "PROJ-123"}

# OpenAPI spec
GET http://localhost:47001/api/openapi.json

# Interactive playground
GET http://localhost:47001/playground

Hoặc mở playground bằng lệnh:

localmcp playground

Danh sách services

| Service | HTTP endpoint | Tài liệu | |---------|---------------|----------| | Figma | /mcp/figma | EN / VI | | Atlassian | /mcp/atlassian | EN / VI | | Google Chat | /mcp/google-chat | EN / VI |

Endpoint /mcp là combined — gộp tất cả services đang active vào một server, tên tool có prefix theo service (figma_, atlassian_, gchat_).

Mỗi service chỉ được bật khi đủ biến môi trường. Xem tài liệu từng service để biết biến nào cần thiết.

Thêm service mới

1. Tạo cấu trúc thư mục

src/services/<tên-service>/
  index.ts          # export registerXxxTools(server)
  client.ts         # axios client hoặc SDK wrapper
  types.ts          # TypeScript types
  tools/
    <feature>.ts    # đăng ký tool với server.registerTool(...)

2. Đăng ký vào service registry

Mở src/index.ts, thêm vào SERVICE_REGISTRY:

import { registerXxxTools } from "./services/xxx/index.js";

const SERVICE_REGISTRY = {
  // ...services hiện có...
  xxx: { register: registerXxxTools, combinedPrefix: "xxx", enabled: !!env.xxx },
};

3. Thêm biến môi trường

Mở src/shared/env.ts, thêm optional group mới:

export const env = {
  // ...
  xxx: optionalGroup(["XXX_API_KEY"], () => ({
    API_KEY: process.env["XXX_API_KEY"]!,
  })),
};

Thêm vào .env.example:

XXX_API_KEY=

4. Viết tài liệu

Tạo docs/<tên-service>.md và docs/vi/<tên-service>.md, sau đó thêm dòng vào bảng Danh sách services ở cả hai README.