Free MCP Core
Library-form fork of freee/freee-mcp. Exposes the MCP server framework, API client, OpenAPI schema loader, and skill resources as npm library exports for use as a dependency, while preserving upstream CLI binary compatibility.
Ask AI about Free MCP Core
Powered by Claude · Grounded in docs
I know everything about Free MCP Core. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
free-mcp-core
Library-form fork of freee/freee-mcp. Exposes the MCP server framework, freee API client, OpenAPI schema loader, and skill resources as npm library exports for use as a dependency, while preserving upstream CLI binary compatibility.
This package is a community fork. It is not maintained by freee K.K. The upstream freee-mcp package ships only CLI binaries with no main/module/exports field, so its internals cannot be imported. free-mcp-core adds an exports map so downstream projects can wrap, extend, or compose freee-mcp's MCP tools without forking the entire repository.
Installation
npm install free-mcp-core
Requires Node.js 22+.
When to use
Use free-mcp-core if you want to:
- Build a domain-specific MCP server on top of freee API plumbing (e.g., accounting auditing, custom workflow tools, logic solvers)
- Add your own MCP tools alongside the standard freee tools without maintaining a fork
- Reuse freee-mcp's authenticated API client (
makeApiRequest) in non-MCP contexts - Bundle the freee-api skill content via MCP resources for universal client compatibility
If you only want the CLI binary (no library use), the upstream freee-mcp is the canonical choice.
Library Usage
Minimal MCP server
import {
createMcpServer,
loadConfig,
initLogger,
initUserAgentTransportMode,
} from 'free-mcp-core';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
initUserAgentTransportMode('stdio');
initLogger({ transportMode: 'stdio' });
const config = await loadConfig();
const server = createMcpServer(config);
const transport = new StdioServerTransport();
await server.connect(transport);
This produces a server identical to the upstream freee-mcp CLI: standard freee API tools, OAuth handling, file upload, and bundled skill resources.
Adding your own tools
import { createMcpServer, loadConfig } from 'free-mcp-core';
const server = createMcpServer(await loadConfig());
server.registerTool(
'my_custom_tool',
{ description: '...', inputSchema: { ... } },
async (args) => { /* ... */ },
);
Adding your own skill resources
import {
createMcpServer,
registerSkillResources,
loadConfig,
} from 'free-mcp-core';
const server = createMcpServer(await loadConfig());
// Core's bundled freee-api-skill is auto-registered.
// Register your additional skills:
registerSkillResources(server, { skillsDir: './my-skills' });
Skipping bundled skills
const server = createMcpServer(config, { skipBundledSkills: true });
Direct API client access
import { makeApiRequest, loadConfig, initLogger } from 'free-mcp-core';
await loadConfig();
initLogger();
const response = await makeApiRequest({ /* ... */ });
Skill install helpers (for downstream wrappers)
import {
installSkillsFrom,
updateSkillsFrom,
uninstallSkillsFrom,
parseSkillCommandArgs,
getBundledSkillsDir,
} from 'free-mcp-core';
// Install both core's bundled skills and your own
const opts = parseSkillCommandArgs(process.argv.slice(2));
installSkillsFrom(getBundledSkillsDir(), opts);
installSkillsFrom('./my-skills', opts);
CLI Usage (preserved from upstream)
# Interactive OAuth configuration
npx freee-mcp configure
# Start MCP server (stdio)
npx freee-mcp
# Other binaries (remote HTTP mode, freee-sign)
npx freee-remote-mcp
npx freee-sign-mcp
npx freee-sign-remote-mcp
# Skill management (added in this fork)
npx freee-mcp install-skills [--global|--local] [--force]
npx freee-mcp update-skills [--global|--local]
npx freee-mcp uninstall-skills [--global|--local]
--global targets ~/.claude/skills/ (default). --local targets <cwd>/.claude/skills/.
Bundled Skills
This package ships skills/freee-api-skill/ (forked from upstream freee/freee-mcp under Apache-2.0). The skill content is exposed two ways:
- MCP resources (universal): every markdown file under
skills/is registered with URIskill://<skill-name>/<path>. Any MCP client (Claude Code, Cursor, Cline, etc.) can list and read them via the standard MCP resources/list and resources/read methods. No additional install required. - Claude Code skill format (auto-injection): run
npx freee-mcp install-skillsto copy them into~/.claude/skills/so Claude Code can auto-inject them based on frontmatter matching.
Relationship to upstream
This package is a derivative work of freee/freee-mcp, tracked from a v0.25.4 baseline. The CLI binaries (freee-mcp, freee-remote-mcp, freee-sign-mcp, freee-sign-remote-mcp) remain behavior-compatible with upstream.
The additional surface area introduced by this fork:
exports/main/typesmap in package.json for library consumptionsrc/lib.tsre-exporting the public APIsrc/skills-path.tsfor resolving the bundledskills/directory at runtimesrc/mcp/skill-resources.tsfor exposing skill content as MCP resourcessrc/cli/skills.tsandinstall-skills/update-skills/uninstall-skillsCLI subcommands
We welcome upstream PRs to add library exports directly to freee/freee-mcp. This package exists to provide that surface in the meantime.
License
Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
- Original code: Copyright 2024-present freee K.K.
- Modifications for library use: chisakiShinichirouToshiyuki
freee, freee会計, and related marks are trademarks of freee K.K. Use of those marks in this README is for descriptive purposes only and does not imply endorsement.
